为什么有这个功能？

Why This Feature?

您遇到了来自营销团队的 Franck 和专业测试人员 Lisa，三人开始讨论新功能、提出问题并寻找具体示例。丽莎问：“为什么有这个功能？” Franck 解释说，其基本原理是通过游戏化方法奖励最近的忠实客户，以提高客户保留率，并建议在维基百科上提供有关该主题的链接。丽莎对要点和主要场景做了一些笔记。

You meet Franck, from the marketing team, and Lisa, a professional tester, and the three of you start talking about the new feature, asking questions, and looking for concrete examples. Lisa asks, “Why this feature?” Franck explains that the rationale is to reward recent loyal customers in order to increase customer retention, in a gamification approach, and suggests a link on Wikipedia about that topic. Lisa takes some notes about the main points and main scenarios.

所有这一切都进行得很快，因为每个人都围坐在桌子旁，而且沟通很容易。此外，具体的例子使人们更容易理解和澄清任何开始不清楚的事情。一旦一切都清楚了，每个人都会回到自己的办公桌上。现在轮到丽莎写下最重要的场景并将其发送给每个人。（上次轮到 Franck 了。）现在您可以从这里开始编码。

All this goes quickly because everyone is around the table, and communication is easy. Also, the concrete examples make it easier to understand and clarify anything that starts out unclear. Once it’s all clear, everyone gets back to their desk. It’s Lisa’s turn to write down the most important scenarios and send them to everyone. (Last time it was Franck’s turn.) Now you can start coding from that.

在你以前的工作经验中，这个过程并不是这样进行的。团队通过充满歧义、难以阅读的文档相互交谈。你微笑。您快速将第一个场景转变为自动化验收测试，观察它失败，然后开始编写代码以使其通过绿色测试。

In your previous work experience, the process did not work like this. Teams talked to each other through hard-to-read documents full of ambiguities. You smile. You quickly turn the first scenario into an automated acceptance test, watch it fail, and start writing code to make it pass to green.

你有一种美好的感觉，你将能够把宝贵的时间花在重要的事情上，而不是别的。

You have the nice feeling that you’ll be able to spend your valuable time on what matters and nothing else.

明天你将不再需要这张草图

Tomorrow You Won’t Need This Sketch Anymore

那天下午，两位同事乔治和埃丝特向团队询问需要做出的设计决策。你们在白板周围会面，并在绘制草图时快速评估每个选项。此时您不需要太多 UML ^{1 ，只需要一些自定义框和箭头。}您只想确保每个人现在都理解它。几分钟后，选择了一个解决方案。该计划是在消息系统中使用两个不同的主题；做出这一决定的理由是需要在收到的订单和装运请求之间进行完全隔离。

That afternoon, a pair of colleagues, Georges and Esther, ask the team about a design decision that needs to be made. You meet around the whiteboard and quickly evaluate each option while sketching. You don’t need much UML¹ at this point, just some custom boxes and arrows. You just want to make sure everybody understands it right now. A few minutes later a solution is chosen. The plan is to use two different topics in the messaging system; the rationale for this decision is the need for full isolation between the incoming orders and the shipment requests.

1.统一建模语言： http://www.uml.org/

1.Unified Modeling Language: http://www.uml.org/

Esther 用手机给白板拍了一张照片，以防有人在白天擦掉白板。但她知道，半天之内，就会实施，然后她就可以安全地删除手机里存储的图片了。一小时后，当她提交创建新的消息传递主题时，她小心翼翼地在提交注释中添加了“传入订单和发货请求之间的隔离”的基本原理。

Esther takes a picture of the whiteboard with her phone, just in case someone erases the whiteboard during the day. But she knows that in half a day, it will be implemented, and she can then safely delete the picture stored in her phone. One hour later, when she commits the creation of the new messaging topic, she takes care to add the rationale “isolation between incoming orders and shipment requests” in the commit comment.

第二天，昨天不在的德拉戈斯注意到了新代码，并想知道为什么会这样。他git blame上线后立即得到了答案。

The next day, Dragos, who was away yesterday, notices the new code and wonders why it’s like that. He runs git blame on the line and immediately gets the answer.

抱歉，我们没有营销文件！

Sorry, We Don’t Have Marketing Documents!

一周后，新的营销经理米歇尔接替了弗兰克。米歇尔比弗兰克更注重保留客户。她想知道应用程序在客户保留方面已经实施了哪些措施，因此她要求提供相应的营销文档，但她惊讶地发现没有。

A week later, a new marketing manager, Michelle, replaces Franck. Michelle is more into customer retention than Franck. She wants to know what’s already implemented in the application in the area of customer retention, so she asks for the corresponding marketing document, and she is surprised to learn there is none.

“你不可能是认真的！” 她首先说。但您很快就向她展示了网站，其中包含每次构建期间生成的所有验收测试。顶部有一个搜索区域，因此她可以输入“客户保留”并进行搜索。她单击“提交”并发现结果：

“You can’t be serious!” she first says. But you quickly show her the website with all the acceptance tests produced during each build. There’s a search area on top so she can enter “customer retention” and search on it. She clicks submit and discovers the results:

点击这里查看代码图片

Click here to view code image

1 为了提高客户保留率
2 作为营销人员
3 我想为最近的忠实客户提供折扣
4
5 场景：近期忠诚客户下次购买可享受 10 美元折扣
顾客
6 ...
\7
8 场景：最近的忠实客户在该网站购买过 3 次
上星期
9 ...

1  In order to increase customer retention
2  As a marketing person
3  I want to offer a discount to recent loyal customers
4
5  Scenario: 10$ off on next purchase for recent loyal
customer
6  ...
\7
8  Scenario: Recent loyal customers have bought 3 times in the
last week
9  ...

结果列表显示了许多有关最近忠实客户的特别折扣的场景。米歇尔微笑着。她甚至不必浏览营销文档即可找到她正在寻找的知识。而且这些场景的精确程度远远超出了她的预期。

The result list displays many scenarios about the special discount for recent loyal customers. Michelle smiles. She didn’t even have to browse a marketing document to find the knowledge she was looking for. And the level of precision of these scenarios well exceeds what she was expected.

“我们可以为用欧元购买商品提供同样的折扣吗？” 米歇尔问道。你回答说：“我不确定代码能否很好地管理货币，但我们试试吧。” 在 IDE ²中，您更改验收测试中的货币，然后再次运行测试。他们失败了，所以你知道需要做一些工作来支持这一点。米歇尔几分钟内就得到了答案。她开始认为你的团队与她以前的工作环境相比有一些特别之处。

“Could we do the same discount for purchases in euro?” Michelle asks. You reply, “I’m not sure the code manages currencies well, but let’s just try.” In your IDE², you change the currency in the acceptance test, and you run the tests again. They fail, so you know some work will need to be done to support that. Michelle has her answer within minutes. She begins to think that your team has something special compared to her former work environments.

2.集成开发环境（IDE）。

2.integrated development environment (IDE).

你一直用这个词，但这不是它的意思

You Keep Using This Word, but This Is Not What It Means

第二天，米歇尔又提出了一个问题：购买和订单有什么区别？

The next day Michelle has another question: What is the difference between a purchase and an order?

通常她只会要求开发人员查看代码并解释其中的差异。然而，该团队已经预料到了这个问题，并且该项目的网站包含了一个术语表。“这个术语表是最新的吗？” 她问。“是的，”你回答道。“它会在每次构建期间自动从代码中更新。” 她很惊讶。为什么不是每个人都这样做呢？“为此，你需要让你的代码与业务领域紧密结合”，你简单地说，尽管你很想详细说明你非常热衷的 Eric Evans 的《领域驱动设计 3》一书中的无处不在的^语言。

Usually she would just ask the developers to look in the code and explain the difference. However, this team has anticipated the question, and the project’s website includes a glossary. “Is this glossary up-to-date?” she asks. “Yes,” you reply. “It’s updated during every build—automatically from the code.” She’s surprised. Why doesn’t everybody do that? “You need to have your code closely in line with the business domain for that,” you say simply, though you’re tempted to elaborate on the ubiquitous language from Eric Evans’s book Domain-Driven Design³ you’re so enthusiastic about.

3.埃文斯，埃里克。领域驱动设计：解决软件核心的复杂性。霍博肯：Addison-Wesley Professional，2003。

3.Evans, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Hoboken: Addison-Wesley Professional, 2003.

查看术语表时，米歇尔发现了命名中以前没有人发现的混乱，她建议用正确的名称修复术语表。但这不是这里的工作方式。您首先要在代码中修复名称。您重命名该类并再次运行构建，瞧，术语表现在也已修复。每个人都很高兴，你刚刚学到了一些关于电子商务业务的新知识。

Looking at the glossary, Michelle discovers a confusion that nobody has spotted before in the naming, and she suggests fixing the glossary with the correct name. But this is not the way it works here. You want to fix the name first and foremost in the code. You rename the class and run the build again, and—voilà—the glossary is now fixed as well. Everybody is happy, and you just learned something new about the business of e-commerce.

给我看大局，你就会发现哪里出了问题

Show Me the Big Picture, and You’ll See What’s Wrong There

现在您想删除两个模块之间的有毒依赖关系，但您对完整的代码库不是很熟悉，因此您向 Esther 索要依赖关系图，因为她对此最了解。但即使是她也不记得每一个依赖。“我将根据代码生成依赖关系图。这是我一直想做的事情。这将花费我几个小时，但之后就永远完成了，”她说。

Now you’d like to remove a toxic dependency between two modules, but you’re not very familiar with the full codebase, so you ask Esther for a dependency diagram, since she has the most knowledge of that. But even she does not remember every dependency. “I’ll generate a diagram of the dependencies from the code. It’s something I’ve long wanted to do. This will take me a few hours, but then it’ll be done forever,” she says.

Esther 已经了解了一些开源库，她可以使用这些库轻松地从类或包中提取依赖项，并且她很快将其中一个连接到 Graphviz，这是一款自动进行布局的神奇图表生成器。几个小时后，她的小工具生成了依赖关系图。你得到了你想要的，你很高兴。然后，她额外花了半个小时将此工具集成到构建中。

Esther already knows about a few open-source libraries she can use to easily extract the dependencies from a class or a package, and she quickly wires one to Graphviz, the magical diagram generator that does the layout automatically. A few hours later, her little tool generates the diagram of dependencies. You get what you wanted, and you’re happy. She then spends an extra half hour integrating this tool into the build.

但有趣的是，当 Esther 第一次查看生成的图表时，她注意到一些有趣的事情：两个模块之间不应该存在的依赖关系。通过将她脑海中的系统视图与生成的实际系统视图进行比较，很容易发现设计缺陷。

But the funny thing is that when Esther first looks at the generated diagram, she notices something intriguing: a dependency between the two modules that should not be there. By comparing her mental view of the system with the generated view of the actual system, it was easy to spot the design weakness.

在下一个项目迭代中，设计弱点得到修复，并且在下一个构建中，依赖关系图会自动更新。它变得更加清晰。

In the next project iteration, the design weakness is fixed, and in the next build, the dependency diagram is automatically updated. It becomes a much cleaner diagram.

活文档的未来就在眼前

The Future of Living Documentation Is Now

这个故事与未来无关。它已经在这里了，现在，而且已经在这里很多年了。用小说作家威廉·吉布森的话来说，“未来已经到来，只是分布尚未均匀”。

This tale is not about the future. It is already here, right now, and it has been here for years already. To quote fiction writer William Gibson, this “future has arrived, it’s just not evenly distributed yet.”

工具在这里。技巧就在这里。人们多年来一直在这样做，但它还不是主流。这很遗憾，因为这些对于软件开发团队来说是强大的想法。

The tools are here. The techniques are here. People have been doing all this for ages, but it’s not yet mainstream. That’s a pity because these are powerful ideas for software development teams.

在接下来的章节中，我们将介绍所有这些方法和许多其他方法，您将学习如何在项目中实现它们。

In the following chapters, we’ll go through all these approaches and many others, and you’ll learn how to implement them in your projects.

通常，文档并不酷

Documentation Is Not Cool, Usually

当您听到文档这个词时，您会想到什么？以下是您可能给出的一些答案：

What comes to mind when you hear the word documentation? Here are a few of the answers you might give:

• 这很无聊。

• It’s boring.

• 它涉及编写大量文本。

• It involves writing lots of text.

• 这意味着尝试使用 Microsoft Word，同时又不失去对图片放置的理智。

• It means trying to use Microsoft Word without losing your sanity with picture placement.

• 作为一名开发人员，我喜欢展示运动和行为的动态、可执行的东西。对我来说，文档就像一株静止且干燥的死植物。

• As a developer, I love dynamic, executable stuff that exhibits motion and behavior. To me, documentation is like a dead plant that’s static and dry.

• 它应该是有帮助的，但它经常会产生误导。

• It’s supposed to be helpful, but it’s often misleading.

• 创建文档是一件无聊的苦差事。我更喜欢编写代码而不是编写文档（参见图 1.1）！

• Creating documentation is a boring chore. I’d prefer to be writing code instead of doing documentation (see Figure 1.1)!

文档需要花费大量时间来编写和维护，它很快就会过时，通常充其量是不完整的，而且一点也不有趣。文档是令人沮丧的一个极好的来源。我很抱歉让您就这样一个无聊的话题进行这次旅程。

Documentation takes a lot of time to write and to maintain, it becomes obsolete quickly, it is typically incomplete at best, and it is just not fun. Documentation is a fantastic source of frustration. And I’m sorry to bring you on this journey on such a dull topic.

文档的缺陷

The Flaws of Documentation

传统文档存在许多缺陷和一些常见的反模式。反模式描述了对重复出现的问题的常见响应，该响应被认为不是一个好主意，应该避免。

Traditional documentation suffers from many flaws and several common anti-patterns. An anti-pattern describes a common response to a recurring problem that is considered not a good idea and that should avoided.

以下各节描述了一些最常见的文档缺陷和反模式。您在自己的项目中认识其中的一些吗？

Some of the most frequent flaws and anti-patterns of documentation are described in the following sections. Do you recognize some of them in your own projects?

单独的活动

即使在声称敏捷的软件开发项目中，决定构建什么以及进行编码、测试和准备文档也常常是独立的活动，如图 1.2所示。

Even in software development projects that claim to be agile, deciding what to build and doing the coding, testing, and preparing documentation are too often separate activities, as illustrated in Figure 1.2.

单独的活动会导致大量浪费和失去机会。基本上，在每项活动中都会操纵相同的知识，但以不同的形式和方式在不同的工件中——并且可能有一定数量的重复。此外，这种“相同”的知识可能会在过程本身中演变，这可能会导致不一致。

Separate activities induce a lot of waste and lost opportunities. Basically, the same knowledge is manipulated during each activity, but in different forms and in different artifacts—and probably with some amount of duplication. In addition, this “same” knowledge can evolve during the process itself, which may cause inconsistencies.

手动转录

当需要制作文档时，团队成员会选择一些已完成工作的知识元素，并手动转录为适合预期受众的格式。基本上，这意味着编写另一份关于代码中刚刚完成的操作的文档，就像古腾堡之前的抄写员一样（参见图 1.3）。

When the time comes to do documentation, members of the team select some elements of knowledge of what has been done and perform a manual transcription into a format suitable for the expected audience. Basically, it means writing another document about what has just been done in the code—like copyists before Gutenberg (see Figure 1.3).

无聊的时间沉没

经理们需要为用户提供文档，并应对团队的人员流动。然而，开发人员讨厌编写文档。与编写代码或自动化任务相比，这并不有趣。对于开发人员来说，快速过时且无法执行的死文本并不是特别令人兴奋。当开发人员处理文档时，他们更愿意处理真正可以工作的软件。矛盾的是，当他们想要重用第三方软件时，他们常常希望它有更多可用的文档。

Managers want documentation for the users and also to cope with the turnover in the team. However, developers hate writing documentation. It is not fun compared to writing code or compared to automating a task. Dead text that gets obsolete quickly and that does not execute is not particularly exciting to write for a developer. When developers are working on documentation, they’d prefer to be working on the real working software instead. Paradoxically, when they want to reuse third-party software, they often wish it had more documentation available.

技术作家喜欢编写文档并为此付费。然而，为了获得所需的技术知识，他们通常需要开发人员，而且通常他们仍在手动转录知识。这一切都很令人沮丧，并且消耗了大量宝贵的时间（见图1.4）。

Technical writers like to do documentation and are paid for that. However, to get access to the technical knowledge required, they usually need developers, and often they’re still doing manual transcription of knowledge. This is all frustrating and consumes a lot of precious time (see Figure 1.4).

大脑转储

因为编写文档并不有趣，而且只是因为必须要做而完成，所以常常是随意完成的，没有经过太多思考。结果是随机的作者在写作时的想法（见图1.5）。问题是这样的随机大脑转储对任何人都没有帮助。

Because writing documentation is not fun and is done because it simply has to be done, it is often done arbitrarily, without much thinking. The result is a random brain dump of what the writer had in mind at the time of writing (see Figure 1.5). The problem is that such a random brain dump is not helpful to anyone.

误导性帮助

只要文档没有严格保持最新，就会产生误导，如图1.6所示。虽然它假装有帮助，但这是错误的。因此，此类文档读起来可能很有趣，但试图找出哪些内容仍然正确、哪些内容变得不正确会带来额外的认知负担。

Whenever documentation is not strictly kept up-to-date, it becomes misleading, as pictured in Figure 1.6. Although it pretends to help, it is incorrect. As a result, such documentation may be interesting to read, but there’s an additional cognitive load involved in trying to find out what’s still correct versus what’s become incorrect.

敏捷宣言和文档

The Agile Manifesto and Documentation

敏捷宣言由一群软件从业者于 2001 年撰写。在其中，他们列出了他们所重视的内容，包括以下内容：

The Agile Manifesto was written by a group of software practitioners in 2001. In it, they list what they have come to value, including the following:

• 流程和工具上的个体和交互

• Individuals and interactions over processes and tools

• 工作软件胜过全面的文档

• Working software over comprehensive documentation

• 客户协作胜过合同谈判

• Customer collaboration over contract negotiation

• 响应变化而不是遵循计划

• Responding to change over following a plan

第二个偏好，“工作软件胜过全面文档”，经常被误解。许多人认为它完全无视文档。事实上，敏捷宣言并没有说“不要做文档”。这只是一个偏好问题。用宣言作者的话来说，“我们拥抱文档，但不把大量纸张浪费在从未维护和很少使用的大部头书籍中。” ⁴尽管如此，随着敏捷方法成为大公司的主流，误解仍然存在，许多人忽视了文档。

The second preference, “Working software over comprehensive documentation,” is frequently misunderstood. Many people believe that it disregards documentation completely. In fact, the Agile Manifesto does not say “don’t do documentation.” It’s only a matter of preference. In the words of the authors of the manifesto, “We embrace documentation, but not to waste reams of paper in never-maintained and rarely-used tomes.”⁴ Still, with agile approaches becoming mainstream in larger corporations, the misunderstanding is still there, and many people neglect documentation.

4.马丁·福勒和吉姆·海史密斯， http://agilemanifesto.org/history.html

4.Martin Fowler and Jim Highsmith, http://agilemanifesto.org/history.html

然而，我最近注意到，缺乏文档是我的客户和同事感到沮丧的一大根源，而且这种沮丧感越来越大。2013 年在瑞典举行的 Öredev 会议上，我首次提到活文档后，我很惊讶地发现人们对文档主题抱有浓厚的兴趣。

However, I’ve noticed recently that the lack of documentation is a big source of frustration for my customers and colleagues, and this frustration is getting bigger. I was surprised to see some great appetite for the topic of documentation after I first mentioned living documentation at the Öredev conference in Sweden in 2013.

现在是文档 2.0 的时候了

It’s Time for Documentation 2.0

传统的文档存在缺陷，但现在我们知道得更多了。自 20 世纪 90 年代末以来，干净代码、测试驱动开发 (TDD)、行为驱动开发 (BDD)、领域驱动设计 (DDD) 和持续交付等实践已变得越来越受欢迎。所有这些实践都改变了我们对交付软件的思考方式。

Traditional documentation is flawed, but now we know better. Since the end of the 1990s, practices like clean code, test-driven development (TDD), behavior-driven development (BDD), domain-driven design (DDD), and continuous delivery have become increasingly popular. All these practices have changed the way we think about delivering software.

对于 TDD，测试首先被视为规范。通过 DDD，我们可以识别业务领域的代码和建模，打破了模型与代码分开保存的传统。结果之一是我们期望代码能够讲述有关该域的整个故事。BDD 借用了业务语言的思想，并通过工具支持使其更加字面化。最后，持续交付表明，如果我们决定遵循推荐的实践，几年前看起来很荒谬的想法（以非事件方式每天交付几次）实际上是可能的，甚至是可取的。

With TDD, the tests are first considered as specifications. With DDD, we identify the code and the modeling of the business domain, breaking with the tradition of models kept separately from the code. One consequence is that we expect the code to tell the whole story about the domain. BDD borrowed the idea of the business language and made it more literal, with tool support. Finally, continuous delivery is showing that an idea that looked ridiculous a few years ago (delivering several times a day in a non-event fashion) is actually possible and even desirable if we decide to follow the recommended practices.

正在发生的另一件有趣的事情是由于时间的影响：尽管像文学编程或 HyperCard 这样的旧思想没有成为主流，但它们仍然缓慢而悄然地产生影响，特别是在 F# 和 Clojure 等较新的编程语言社区中，它们带来了一些旧观念被推到前台。

Another interesting thing that is happening is due to the effect of time: Even though old ideas like literate programing or HyperCard did not become mainstream, they remained slowly and quietly influential, especially in more recent programming languages communities such as F# and Clojure, which bring some of the old ideas to the foreground.

现在，我们终于可以期待一种有用、始终最新、成本低廉且创建起来充满乐趣的文档方法。我们承认传统记录方法存在的所有问题，并且我们也看到有必要予以满足。本书探讨了其他方法并提供了指导，以更有效地满足需求。但首先，让我们探讨一下文档到底是什么。

Now at last we can expect an approach to documentation that is useful, always up-to-date, low cost, and fun to create. We acknowledge all the problems of the traditional approach to documentation, and we also see that there is a need to be fulfilled. This book explores and offers guidance on other approaches to meet the needs in more efficient ways. But first, let’s explore what documentation really is.

知识的起源

The Origination of Knowledge

知识从哪里来？知识主要来自对话。我们通过与其他人的对话发展了很多知识。这种情况发生在集体工作期间，例如结对编程，或在会议期间，或在咖啡机旁，通过电话，或通过公司聊天或电子邮件。对话的示例包括 BDD 规范研讨会和敏捷领域的三个朋友。

Where does knowledge come from? Knowledge primarily comes from conversations. We develop a lot of knowledge through conversations with other people. This happen during collective work such as pair programming, or during meetings, or at the coffee machine, on the phone, or via a company chat or emails. Examples of conversations include BDD specification workshops and the three amigos in agile.

然而，作为软件开发人员，我们也与机器进行对话，我们将这些称为实验。我们通过使用某种编程语言的代码向机器告诉一些信息，机器运行它并告诉我们一些回报：测试失败或变绿，UI 按预期反应，或者结果不是我们想要的，其中如果我们学到新东西。实验示例包括 TDD、新兴设计和精益创业实验。

However, as software developers, we have conversations with machines, too, and we call these experiments. We tell something to a machine by using code in some programming language, and the machine runs it and tells us something in return: The test fails or goes green, the UI reacts as expected, or the result is not what we wanted, in which case we learn something new. Examples of experiments include TDD, emerging design, and Lean Startup experiments.

知识也来自对上下文的观察。在公司里，只要呆在公司，关注其他人的谈话、行为和情绪，你就能学到很多东西。观察的例子包括领域沉浸、痴迷墙、信息辐射器和精益创业“走出大楼”观察。

Knowledge also comes from observation of the context. In a company, you learn a lot by just being there, paying attention to other people’s conversations, behavior, and emotions. Examples of observation include domain immersion, obsession walls, information radiators, and Lean Startup “Get out of the building” observation.

知识来自于与人的对话以及在可观察的环境中对机器进行的实验。

Knowledge comes from conversations with people and experiments with machines in an observable context.

知识如何演化？

How Does Knowledge Evolve?

有些知识可以稳定数年，而另一些知识则在数月甚至数小时内频繁变化。

Some knowledge can be stable for years, whereas other knowledge changes frequently over months or even hours.

任何形式的文档都必须考虑维护成本并使其尽可能接近于零。为了获得稳定的知识，传统的文档方法是有效的。但随着知识的频繁变化，编写文本并在每次更改后更新它是不可行的。

Any form of documentation has to consider the cost of maintenance and make it as close to zero as possible. For stable knowledge, traditional methods of documentation work. But with frequently changing knowledge, writing text and updating it after every change is just not an option.

软件行业加速的结果是我们希望能够非常快速地发展软件。速度如此之快，以至于不可能花时间编写一页又一页的文档，但我们想要文档的所有好处。

The effect of acceleration in the software industry is that we want to be in a position to evolve the software very quickly. The speed is such that it’s impossible to spend time writing pages and pages of documentation, and yet we want all the benefits of documentation.

为什么需要知识

Why Knowledge Is Necessary

在创建软件时，我们会在学习过程中遇到很多问题、做出决定和调整：

When creating software, we go through a lot of questions, decisions, and adjustments as we learn:

• 我们要解决什么问题？从现在开始大家都应该知道了。

• What problem are we trying to solve? Everyone should know it from now on.

• 我们真正想解决什么问题？（当我们意识到我们最初弄错了时，我们会尝试回答这个问题。）

• What problem are we really trying to solve? (We try to answer this when we realize we got it wrong initially.)

• 我们一直混淆trade和deal，但我们最终意识到它们不是同义词。我们不应该再次混淆他们。

• We’ve been confusing trade and deal, but we eventually realized that they are not synonyms. We should not confuse them again.

• 我们尝试了这个新的数据库，但它不符合我们的需求，原因有三个。只要我们的需求保持不变，就无需稍后再试。

• We tried this new DB, and it doesn’t match our needs—for three reasons. No need to try again later as long as our needs remain the same.

• 我们决定将购物车模块和支付模块解耦，因为我们注意到其中一个模块的更改与另一个模块的更改无关。我们不应该再次将它们耦合起来。

• We decided to decouple the shopping cart module and the payment module because we noticed that the changes to one had nothing to do with changes to the other. We should not couple them again.

• 我们偶然发现这个功能没什么用，所以我们计划下个月删除该代码。但我们很可能会忘记我们的基本原理，如果代码仍然存在，它将永远是一个谜。

• We found out by chance that this feature is useless, so we plan to delete the code next month. But we are likely to forget our rationale, and if the code remains, it will be a mystery forever.

使用现有的软件，当我们错过以前开发的知识时，我们最终会重做已经完成的事情，因为我们不知道它已经存在。我们最终还会将某个功能放入不相关的组件中，因为我们不知道它应该放在哪里，这使得软件变得臃肿。或者有关该功能的代码变得分散在各个组件中。

With existing software, when we miss the knowledge developed before, we end up redoing what’s already done because we don’t know it’s there already. We also end up putting a feature in an unrelated component because we don’t know where it should be, and this makes the software bloated. Or the code about the feature becomes fragmented across various components.

如果我们有足够的知识来回答以下日常问题就好了：

If only we had the knowledge available to answer everyday questions like the following:

• 我在哪里可以安全地解决该问题？

• Where can I fix that issue safely?

• 我应该在哪里添加此增强功能？

• Where should I add this enhancement?

• 原作者会在哪里添加此增强功能？

• Where would the original authors add this enhancement?

• 删除这行看起来无用的代码是否安全？

• Is it safe to delete this line of code that looks useless?

• 我想更改方法签名，但是这样做会产生什么影响？

• I’d like to change a method signature, but what impacts will result if I do?

• 我真的需要对代码进行逆向工程才能理解它是如何工作的吗？

• Do I really have to reverse engineer the code just to understand how it works?

• 每次业务分析师需要了解当前的业务规则时，我真的需要花时间阅读源代码吗？

• Do I really have to spend time reading the source code each time the business analysts need to know about the current business rules?

• 当客户请求某项功能时，我们如何知道该功能是否已受支持以及是否需要开发？

• When a customer asks for a feature, how do we know if it’s already supported if it needs to be developed?

• 我们感觉我们改进代码的方式是最好的，但是如果我们对它的工作原理缺乏完整的理解怎么办？

• We have the feeling that the way we evolve the code is the best possible, but what if we lack a complete understanding of how it works?

• 我们如何轻松地找到处理特定功能的代码部分？

• How do we easily find the part of the code that deals with a particular feature?

缺乏知识表现为两种成本：

Lack of knowledge manifests as two costs:

• 浪费时间：这些时间本来可以更好地投入到改进其他方面。

• Wasted time: That time could have been better invested in improving something else.

• 次优决策：从长远来看，其他决策可能更相关或更便宜。

• Suboptimal decisions: Other decisions could have been more relevant, or cheaper in the long term.

随着时间的推移，这两项费用会不断增加：花在寻找缺失知识上的时间就是没有花在做出更好决策上的时间。反过来，次优的决策会让我们的生活逐渐变得更加悲惨，直到我们别无选择，只能决定软件不再可维护并重新开始。

These two expenses compound over time: The time spent finding missing knowledge is time not spent on making better decisions. In turn, suboptimal decisions compound to make our life progressively more miserable, until we have no choice but to decide that the software is no longer maintainable and start again.

能够访问对执行开发任务有用的知识听起来是个好主意。

It sounds like a good idea to be able to access the knowledge that is useful to perform the development tasks.

专注于重要的事情

Focusing on What Matters

作为传递有价值知识的一种手段，文档可以采取多种形式：书面文档、面对面的对话、代码、社交工具上的活动，或者在没有必要时什么都不写。

As a means of transferring valuable knowledge, documentation can take many forms: written documents, face-to-face conversations, code, activity on social tools, or nothing at all when it’s not necessary.

通过文档的这个定义，我们可以表达一些重要的原则：

With this definition of documentation, we can express some important principles:

• 长期感兴趣的知识值得记录下来。

• Knowledge that is of interest for a long period of time deserves to be documented.

• 许多人感兴趣的知识值得记录下来。

• Knowledge that is of interest to a large number of people deserves to be documented.

• 有价值或关键的知识可能也需要记录下来。

• Knowledge that is valuable or critical may also need to be documented.

另一方面，您不需要关心这些情况下不存在的知识文档。花时间或精力在上面都是浪费。

On the other hand, you don’t need to care about documentation of knowledge that isn’t in any of these cases. Spending time or effort on it would be a waste.

所考虑的知识的价值很重要。如果知识在足够长的时间内对足够多的人来说不够有价值，则无需付出努力。如果一项知识已经众所周知或仅对一个人有用，或者直到一天结束时才感兴趣，那么就没有必要转移或存储它。

The value of the considered knowledge matters. There’s no need to make the effort to transfer knowledge that’s not valuable enough for enough people over a long enough period of time. If a piece of knowledge is already well known or is useful for only one person, or if it’s only of interest until the end of the day, then there’s no need to transfer or store it.

在从知识传播和保存的角度重新考虑文档到底是什么，以及如何管理文档的一些早期后果之后，现在是时候介绍活文档的中心思想及其核心原则了。

Having reconsidered what documentation really is, in terms of knowledge transmission and preservation, and some early consequences in how it should be managed, it is now time to introduce the central idea of living documentation and its core principles.

可靠的

Reliable

为了有用，文档必须值得信赖；换句话说，它必须是100%可靠的。由于人类从来都不是那么可靠，因此我们需要纪律和工具来帮助提高可靠性。

To be useful, documentation must be trustworthy; in other words, it must be 100% reliable. Since humans are never that reliable, we need discipline and tools to help with reliability.

为了获得可靠的文档，我们依靠以下想法：

To achieve reliable documentation, we rely on the following ideas:

• 利用可用的知识：大多数知识已经存在于项目的工件中，只需要为了文档目的而对其进行利用、增强和管理。

• Exploiting available knowledge: Most of the knowledge is already present in the artifacts of the project, it just needs to be exploited, augmented, and curated for documentation purposes.

• 准确性机制：需要一个准确性机制来保证知识始终保持同步。

• Accuracy mechanism: An accuracy mechanism is needed to ensure that the knowledge is always kept in sync.

省力

Low Effort

活生生的文档必须是省力的，才能在不断变化的环境中可行且可持续；您可以通过以下想法实现这一目标：

A living documentation must be low effort to be feasible and sustainable on ever-changing environments; you can achieve that thanks to the following ideas:

• 简单性：如果没有什么需要声明的，那么文档是最好的，但它是显而易见的。

• Simplicity: Documentation is best if there is nothing to declare, but it’s just obvious.

• 标准优于自定义解决方案：标准应该是已知的，如果情况并非如此，则只需在外部参考（例如，您最喜欢的书籍、作者或维基百科）中引用标准就足够了。

• Standard over custom solutions: Standards are supposed to be known, and if that’s not the case, it is enough to just refer to a standard in an external reference (for example, your favorite books, authors, or Wikipedia).

• 常青内容：总有一些内容不会改变或很少改变，而且这种材料的维护成本并不高。

• Evergreen content: There is always stuff that does not change or that changes very infrequently, and this material does not cost much to maintain.

• 防重构知识：有些事情发生变化时不需要人为的努力。这可能是因为重构工具会自动传播链接的更改，或者因为某些事物固有的知识与该事物本身并置，并且它会随该事物而变化和移动。

• Refactoring-proof knowledge: Some things don’t require human effort when there is a change. This can be because of refactoring tools that automatically propagate linked changes, or because knowledge intrinsic to something is collocated with the thing itself, and it changes and moves with that thing.

• 内部文档：关于事物的附加知识最好位于事物本身，或尽可能接近。

• Internal documentation: Additional knowledge about a thing is best located on the thing itself, or as close as possible.

协作性

Collaborative

活文档必须通过以下偏好进行协作：

A living documentation must be collaborative through the following preferences:

• 优先采用对话而非正式文档：没有什么比交互式、面对面的对话更能有效地交流知识。不要因为没有记录每次讨论而感到难过。尽管我通常喜欢对话，但有些知识在很长一段时间内或对许多人来说一直是有用的。重要的是要注意随着时间的推移，思想沉淀的过程，以确定哪些知识值得以持久的形式记录下来。

• Favor conversations over formal documentation: Nothing beats interactive, face-to-face conversations for exchanging knowledge efficiently. Don’t feel bad about not keeping a record of every discussion. Even though I usually favor conversations, there is knowledge that keeps on being useful repeatedly over a long period of time or for many people. It is important to pay attention to the process of ideas sedimentation over time to decide what knowledge is worth the effort of recording in a persistent form.

• 可访问的知识：在活文档方法中，知识通常在源代码控制系统的技术工件中声明。这使得非技术人员很难访问它。因此，您应该提供工具，使所有受众无需任何手动操作即可获取这些知识。

• Accessible knowledge: In a living documentation approach, knowledge is often declared within technical artifacts in a source control system. This makes it difficult for nontechnical people to access it. Therefore, you should provide tools to make this knowledge accessible to all audiences without any manual effort.

• 集体所有权：并不是因为所有知识都在源代码控制系统中，开发人员才拥有它。开发人员不拥有文档；他们只承担处理它的技术责任。

• Collective ownership: It’s not because all the knowledge is in the source control system that developers own it. Developers don’t own the documentation; they just own the technical responsibility to deal with it.

富有洞察力

Insightful

上述原则很有用，但要充分发挥活文档的潜力，它必须具有洞察力：

The above-mentioned principles are useful, but to realize the full potential of a living documentation, it must be insightful:

• 深思熟虑的决策：如果您不清楚自己在做什么，那么当您准备进行实时记录时，它会立即显示出来。这种反馈鼓励您澄清您的决定，以便您所做的事情变得容易解释。通过鼓励更加深思熟虑的决策，这通常会提高工作质量。

• Deliberate decision making: If you don’t know clearly what you’re doing, it shows immediately when you’re about to do living documentation. This kind of feedback encourages you to clarify your decisions so that what you do becomes easy to explain. By encouraging more deliberate decision-making, this will often raise the quality of the work.

• 嵌入式学习：您希望编写非常好的代码和其他技术工件，以便您的同事只需通过使用系统、通过交互来学习即可学习设计、业务领域和其他所有内容。

• Embedded learning: You want to write code and other technical artifacts that are so good that your workmates can learn the design, the business domain, and everything else just by working with the system, learning through their interactions.

• 现实检查：实时文档有助于揭示系统的实际状态（例如，“我没想到实现会那么混乱”，如“我以为我刮得正确，但镜子告诉我情况并非如此。”）。再次，这可以通过接受现实的本来面目而不是你想要的样子来促进改进。

• Reality check: Living documentation helps reveal the actual state of the system (for example, “I did not expect the implementation to be that messy,” as in “I thought I was shaved correctly, but the mirror tells otherwise.”). This, again, can foster improvements by accepting reality for what it is, as opposed to what you’d like it to be.

以下各节将更详细地描述这些原则，而接下来的章节将扩展至相关模式和实践，以实施成功的活文档方法。但在此之前，令人惊讶的是，我们可以在蚂蚁和其他社会性昆虫协作和交换知识的方式中找到活体记录的重要灵感。

The following sections describe these principles more in details, while the next chapters expand into the related patterns and practices to implement a successful living documentation approach. But before that, an important inspiration for living documentation can be found, surprisingly, in the way ants and other social insects collaborate and exchange knowledge.

蚂蚁如何交换知识：Stigmergy

How Ants Exchange Knowledge: Stigmergy

Michael Feather (@mfeathers) 最近分享了 Ted Lewis 在网上发表的一篇精彩文章的链接，他介绍了与我们作为一个团队在软件领域工作相关的污蔑概念：

Michael Feather (@mfeathers) recently shared a link to a fantastic article online by Ted Lewis, who introduces the concept of stigmergy in relation to our work in software as a team:

同样，程序员通过电子邮件、GitHub 问题和各种增强代码的文档来制造自己的标记。正如刘易斯总结的那样：

Similarly, programmers manufacture their own markers through emails, GitHub issues, and all kinds of documentation that augments code. As Lewis concludes:

Stigmergy 已经成为我们在开发软件时在人与机器之间交换知识的重要方式。活体记录的一个关键思想是承认这种耻辱效应的存在，并找到将其发挥到极致的方法。首先，像蚂蚁一样，从您所在的系统中获取大部分知识。

Stigmergy is already the prominent way we exchange knowledge between the people and the machines involved when doing software. One key idea of living documentation is to acknowledge that this stigmergic effect is there, and to find ways to push it to the max. This starts by getting most of the knowledge out of the system you’re in, like ants do.

内部文档与外部文档

Internal Versus External Documentation

持久性文档有两种形式：外部和内部。

Persistent documentation comes in two flavors: external and internal.

通过外部文档，知识以与项目所选择的实现技术无关的形式表达。这是传统形式的文档的情况，共享文件夹或 wiki 上有单独的 Microsoft Office 文档，并有自己的数据库。

With external documentation, knowledge is expressed in a form that has nothing to do with the chosen implementation technologies of the project. This is the case of the traditional forms of documentation, with separate Microsoft Office documents on shared folders or wikis with their own databases.

外部文档的一个优点是它可以采用对观众和作者来说最方便的任何格式和工具。缺点是要确保外部文档相对于产品的最新版本是最新的，即使不是不可能，也是极其困难的。外部文档也可能会丢失。

An advantage of external documentation is that it can take whatever format and tool is most convenient for the audience and for the writers. The drawback is that it’s extremely hard, if not impossible, to ensure that external documentation is up-to-date with respect to the latest version of the product. External documentation can also simply be lost.

相比之下，内部文档利用现有的实现技术直接表示知识。使用 Java 注释或语言标识符的命名约定来声明和解释设计决策是内部文档的一个很好的例子。

In contrast, internal documentation directly represents knowledge by using the existing implementation technology. Using Java annotations or naming conventions on the language identifiers to declare and explain design decisions is a good example of internal documentation.

内部文档的优点是它始终与产品的任何版本保持同步，因为它是源代码的一部分。内部文档不会丢失，因为它嵌入在源代码本身中。它也很容易获得，并且会引起任何处理代码的开发人员的注意，因为它就在他们的眼前。

The advantage of internal documentation is that it’s always up-to-date with any version of the product, as it’s part of its source code. Internal documentation cannot be lost because it’s embedded within the source code itself. It’s also readily available and comes to the attention of any developers working on the code just because it’s under their eyes.

内部文档还使您能够受益于出色的 IDE 的所有工具和所有优点，例如自动完成、即时搜索以及元素内部和元素之间的无缝导航。缺点是知识的表达仅限于语言内置的可能的扩展机制。例如，您无法通过有关每个依赖项的附加知识来扩展 Maven XML。另一个很大的缺点是，非开发人员不容易获取以内部文档形式表达的知识。然而，可以通过自动化机制来解决这一限制，该机制提取知识并将其转化为适当受众可以访问的文档。

Internal documentation also enables you to benefit from all the tools and all the goodness of your fantastic IDE, such as autocomplete, instant search, and seamless navigation within and between elements. The drawback is that your expression of the knowledge is limited to the possible extension mechanisms built in to the language. For example, there’s little you can do to extend the Maven XML with additional knowledge about each dependency. Another big drawback is that knowledge expressed as internal documentation is not readily accessible to nondevelopers. However, it is possible to work around that limitation with automated mechanisms that extract the knowledge and turn it into documents that are accessible to the right audience.

如果您熟悉Martin Fowler 和 Rebecca Parsons 所著的《领域特定语言》一书，您就会认识到内部与外部的类似概念领域特定语言 (DSL)。外部 DSL 独立于所选的实现技术。例如，正则表达式的语法与为项目选择的编程语言无关。相比之下，内部 DSL 使用常规选择的技术，例如 Java 编程语言，其方式使其看起来像是另一种伪装的语言。这种风格通常称为流畅风格，在模拟库中很常见。

If you’re familiar with the book Domain-Specific Languages by Martin Fowler and Rebecca Parsons, you’ll recognize the similar concept of internal versus external domain-specific languages (DSLs). An external DSL is independent from the chosen implementation technology. For example, the syntax of regular expressions has nothing to do with the programming language chosen for the project. In contrast, an internal DSL uses the regular chosen technology, such as the Java programming language, in a way that makes it look like another language in disguise. This style is often called a fluent style and is common in mocking libraries.

内部和外部文档示例

Examples of Internal and External Documentation

区分文档是内部文档还是外部文档并不总是那么容易，因为它有时与您的观点有关。Javadoc 是 Java 编程语言的标准部分，因此它是内部的。但从 Java 实现者的角度来看，它是嵌入在 Java 语法中的另一种语法，因此它是外部的。常规代码注释位于灰色中间区域。它们在形式上是语言的一部分，但除了自由文本之外不提供任何东西。你要靠你自己的写作天赋来写它们，编译器除了基于英语词典的默认拼写检查之外，不会帮助检查拼写错误。

It’s not always easy to tell whether documentation is internal or external, as it’s sometime relative to your perspective. Javadoc is a standard part of the Java programming language, so it’s internal. But from the Java implementors’ perspective, it’s another syntax embedded within the Java syntax, so it would be external. Regular code comments are in a gray middle area. They’re formally part of the language but do not provide anything more than free text. You’re on your own to write them with your writing talent, and the compiler will not help check for typos beside the default spell-checking based on the English dictionary.

从开发人员的角度来看，用于构建软件产品的每一项标准技术都可以被视为内部文档的宿主，包括以下内容：

From the perspective of the developer, every standard technology used to build a software product can be considered a host for internal documentation, including the following:

• 用于业务可读规范和测试工具的功能文件

• Feature files used for business-readable specifications and testing tools

• 代码旁边的 Markdown 文件和图像具有命名约定，或者从代码或功能文件链接到

• Markdown files and images next to the code with a naming convention or linked to from the code or feature files

• 工具清单，包括依赖管理清单、自动化部署清单、基础设施描述清单等

• Tools manifests, including the dependency management manifest, automated deployment manifest, infrastructure description manifest, and so on

每当我们在这些工件中添加文档时，我们都会受益于能够使用我们的标准工具集，并具有位于源代码控制中的优势，靠近相应的实现，以便它可以与之一起发展。

Whenever we add documentation within these artifacts, we benefit from being able to use our standard toolset and have the advantage of being in the source control, close to the corresponding implementation so that it can evolve together with it.

内部文档的潜在媒体示例包括：

Examples of potential media for internal documentation include the following:

• 自记录代码和使用干净的代码实践，包括类和方法命名、使用组合方法和类型

• Self-documenting code and use of clean code practices, including class and method naming, using composed methods and types

• 为编程语言元素添加知识的注释

• Annotations that add knowledge to elements of the programming language

• 关于公共接口、类和主要方法的 Javadoc 注释

• Javadoc comments on public interfaces, classes, and main methods

• 文件夹组织以及模块和子模块的分解和命名

• Folder organization and decomposition and naming of modules and submodules

相反，外部文档的示例包括以下内容：

In contrast, examples of external documentation include the following:

• 自述文件和类似的文本文件

• README and similar text files

• 有关该项目的任何 HTML 或 Microsoft Office 文档

• Any HTML or Microsoft Office document about the project

优先选择内部文档

Preferring Internal Documentation

请记住我之前所说的：放置有关事物的文档的最佳位置是事物本身。

Remember what I said earlier: The best place to put documentation about a thing is on the thing itself.

正如您将在本书中看到的那样，我绝对赞成内部文档，并在需要发布更传统文档的情况下加上足够的自动化。我建议默认选择内部文档，至少对于所有有定期更改风险的知识来说是这样。

As you’ll see throughout this book, I’m definitely in favor of internal documentation, coupled with just enough automation for cases where it’s necessary to publish more traditional documents. I suggest choosing internal documentation by default, at least for all knowledge that’s at risk of changing regularly.

即使对于稳定的知识，我也首先推荐内部文档，并且仅当有明显的附加值时我才会选择制作外部文档，例如必须具有最大吸引力的文档（可能出于营销原因）。在这种情况下，我建议手工制作的幻灯片、经过精心手动布局的图表以及吸引人的图片。使用外部文档的目的是能够为最终文档添加人性化的感觉，因此我会使用 Apple Keynote 或 Microsoft PowerPoint，选择或创建精美的高质量图片，并在面板上测试文档的有效性的同事，以确保它受到好评。

Even for stable knowledge, I recommend internal documentation first, and I would choose to do external documentation only when there’s clearly value added, such as with a documentation that must be maximally attractive (perhaps for marketing reasons). In that case, I suggest hand-crafted slides, diagrams with careful manual layout, and appealing pictures. The point of using external documentation would be to be able to add a human feel to the final document, so I’d use Apple Keynote or Microsoft PowerPoint, select or create beautiful quality pictures, and beta test the effectiveness of the documentation on a panel of colleagues to make sure it’s well received.

请注意，吸引力和幽默可能很难自动化或编码到正式文档中，但这也不是不可能的。

Note that appeal and humor can be hard to automate or to encode into formal documentation, but it’s not impossible either.

现场记录

In Situ Documentation

内部文档，也称为现场文档，是指“处于自然或原始位置或地点”的文档。¹⁰

Internal documentation, also an in-situ documentation, means documentation that is “in the natural or original position or place.”¹⁰

10.经许可。来自 Merriam-Webster.com © 2019 Merriam-Webster, Inc. https://www.merriam-webster.com/dictionary/insitu。

10.By Permission. From Merriam-Webster.com © 2019 by Merriam-Webster, Inc. https://www.merriam-webster.com/dictionary/insitu.

这意味着文档不仅使用相同的实现技术，而且还直接混合到构建产品的工件内的源代码中。就地意味着将有关事物所在位置的附加知识带来，例如在源代码中而不是在远程位置。

This implies that the documentation is not only using the same implementation technology, but is also directly mixed into the source code, within the artifact that built the product. In situ means bringing the additional knowledge about a thing where the thing is located, for example within the source code rather than in a remote location.

这种类型的文档对于开发人员来说很方便。与设计用户界面一样，术语“原位”意味着可以在不进入另一个窗口的情况下执行特定的用户操作，而可以在不进入另一个文件或另一个工具的情况下执行文档的使用和编辑。

This type of documentation is convenient for developers. As in designing user interfaces, where the term in situ means that a particular user action can be performed without going to another window, consuming and editing the documentation can be performed without going to another file or to another tool.

机器可读文档

Machine-Readable Documentation

好的文档侧重于高级知识，例如代码之上的设计决策以及这些决策背后的基本原理。我们通常认为这种知识只有人们才感兴趣，但即使是工具也可以利用它。由于内部文档是使用实现技术来表达的，因此通常可以通过工具来解析。这为帮助开发人员完成日常任务的工具提供了新的机会。特别是，它可以实现知识的自动处理，以进行管理、整合、格式转换、自动发布或协调。

Good documentation focuses on high-level knowledge like the design decisions on top of the code and the rationale behind these decisions. We usually consider this kind of knowledge to be of interest only to people, but even tools can take advantage of it. Because internal documentation is expressed using implementation technologies, it can usually be parsed by tools. This opens new opportunities for tools to assist developers in their daily tasks. In particular, it enables automated processing of knowledge for curation, consolidation, format conversion, automated publishing, or reconciliation.

学习通用知识

Learning Generic Knowledge

您还可以通过工作、阅读书籍以及参加培训和会议来学习通用知识。这只需要几个小时，而且你事先知道你要学什么、需要多长时间以及需要花多少钱。学习通用知识就像去商店买食物一样容易。

You also learn generic knowledge by doing your job, as well as by reading books and attending trainings and conferences. This only takes a few hours, and you know beforehand what you’re going to learn, how long it will take, and how much it will cost. It’s as easy to learn generic knowledge as it is to go to the store to buy food.

通用知识是一个已解决的问题。这些知识是现成的，可供每个人重复使用。当您使用它时，您只需链接到权威来源即可完成记录。这就像记下互联网链接或参考书目一样简单。

Generic knowledge is a solved problem. This knowledge is ready-made, ready to be reused by everyone. When you use it, you just have to link to an authoritative source, and you’re done documenting. This is as simple as noting an Internet link or a bibliographic reference.

专注于特定知识

Focusing on Specific Knowledge

使用特定知识的文档并从培训中学习通用知识。

Use documentation for specific knowledge and learn the generic knowledge from trainings.

特定知识是您的公司或团队拥有但尚未与同一行业的其他同行共享的知识。学习这些知识比学习通用知识更昂贵；这需要时间练习和犯错误。这是最值得关注的知识。

Specific knowledge is the knowledge your company or team has that is not (yet) shared with other peers in the same industry. This knowledge is more expensive to learn than generic knowledge; it takes time practicing and making mistakes. This is the kind of knowledge that deserves most attention.

具体的知识是有价值的，并且无法找到现成的，所以这是你必须照顾的知识。特定的知识值得您和您的同事付出最大的努力。作为一名专业人士，您应该了解足够的通用行业标准知识，以便能够专注于增长针对您特定目标的知识。

Specific knowledge is valuable and cannot be found ready-made, so it’s the kind of knowledge you have to take care of. Specific knowledge deserves the biggest efforts from you and your colleagues. As a professional, you should know enough of the generic, industry standard knowledge to be able to focus on growing the knowledge that’s specific to your particular ambitions.

因此：确保每个人都接受过行业通用知识的培训。然后将所有文档工作集中在特定知识上。

Therefore: Make sure everyone is trained on the generic knowledge in your industry. Then focus any documentation effort on specific knowledge.

可靠文档的准确性机制

Accuracy Mechanism for Reliable Documentation

正如前面提到的，可以信任的权威知识已经存在于某处，通常以源代码的形式存在。因此，重复的知识是有问题的，因为它会成倍增加更新知识以跟上变化的成本。当然，这适用于源代码，也适用于所有其他工件。我们通常将“设计”称为确保更改在任何时间点都保持低成本的学科。当然，我们需要代码设计，并且我们需要相同的设计技能来处理有关文档的所有内容。

As mentioned earlier, authoritative knowledge that can be trusted already exists somewhere, usually in the form of source code. Therefore, duplicated knowledge is problematic because it multiplies the cost of keeping it updated to keep pace with changes. This applies to source code, of course, and this applies to every other artifact, too. We usually call “design” the discipline of making sure that changes remain cheap at any point in time. We need design for the code, of course, and we need the same design skills for everything about documentation.

一个好的文档方法是设计问题。需要设计技能来设计始终准确的文档，同时又不会减慢软件开发工作的速度。

A good approach for documentation is a matter of design. It takes design skills to design documentation that is always accurate, without slowing down the software development work.

由于知识随时可能发生变化，因此有多种方法可以保持文档的准确性。以下各节对它们进行了描述，按照从最理想到最不理想的顺序排列，第 3 章“知识利用”对它们进行了扩展。

With knowledge that can change at any time, there are a number of approaches to keeping documentation accurate. They are described in the following sections, ordered from the most desirable to the least desirable, and Chapter 3, “Knowledge Exploitation,” expands on them.

考虑保存在单一来源中的权威知识。这些知识只有能够阅读文件的人才能访问。例如，对于开发人员来说，源代码本身就是一个自然的文档，有了好的代码，就不需要其他任何东西。例如，用于配置 Maven 或 NuGet 等依赖项管理工具的所有依赖项列表的清单是依赖项列表的自然权威文档。只要这些知识只是开发人员感兴趣的，就可以了；不需要发布机制来使其他受众能够访问知识。

Consider a piece of knowledge kept in a single source that is authoritative. This knowledge is accessible only to the people who can read the files. For example, source code is a natural documentation of itself for developers, and with good code, there’s no need for anything else. For example, a manifest to configure the list of all dependencies for a dependency management tool like Maven or NuGet is natural authoritative documentation for the list of dependencies. As long as this knowledge is only of interest for developers, it’s just fine as it is; there’s no need for a publishing mechanism to make the knowledge accessible to other audiences.

当文档不需要准确性机制时

When Documentation Does Not Need an Accuracy Mechanism

在某些情况下，例如在以下部分中，您的文档不需要准确性机制。

In some cases, such as in the following sections, you don’t need an accuracy mechanism for your documentation.

质疑是否需要文档

Questioning the Need for Documentation at All

文档本身并不是目的；这是达到必须确定的目的的手段。除非你理解目标，否则你将无法做出有用的东西。所以第一个问题是：

Documentation is not an end in itself; it’s a mean for a purpose that must be identified. You won’t be able to make something useful unless you understand the goal. So the first question is:

为什么我们需要这个文档？

Why do we need this documentation?

如果没有轻易得到答案，那么您肯定还没有准备好开始在额外的文档上投入精力。你应该暂时搁置这个话题，直到你更加了解为止。您不想将时间浪费在不明确的目标上。

If no answer comes easily, then you’re definitely not ready to start investing effort in additional documentation. You should put the topic on hold until you know better. You don’t want to waste time on ill-defined objectives.

那么下一个问题就随之而来：

Then the next question immediately follows:

目标受众是谁？

Who’s the intended audience?

如果答案不清楚或听起来像“每个人”，那么你还没有准备好开始做任何事情。有效的文档必须针对确定的受众。即使是关于“每个人都应该知道”的事情的文档也必须针对受众，例如“对业务领域只有肤浅了解的非技术人员”。

If the answer is unclear or sounds like “everyone,” then you’re not ready to start doing anything. Efficient documentation must target an identified audience. Even documentation about things “that everyone should know” has to target an audience, such as “nontechnical people with only a superficial knowledge of the business domain.”

现在，您仍决心避免浪费时间，准备好回答第一个问题文档。

Now, still determined to avoid wasting time, you’re ready for the first question of documentation.

有人可能会想要创建一个仅与他或她自己感兴趣的主题相关的文档，或者仅与他或她正在研究该主题的时间相关的文档。也许向 wiki 添加一段文字也没有多大意义。但要求提供文件还有另一个更糟糕的原因。

Someone might be tempted to create documentation on a topic that is only of interest for himself or herself or that is relevant only for the time he or she is working on it. Perhaps it does not make much sense to even add a paragraph to the wiki. But there’s another, and worse, reason for asking for documentation.

由于缺乏信任而需要文档

Need for Documentation Because of Lack of Trust

关于文档的第一个问题的答案可能听起来像“我需要文档，因为我担心你的工作没有我想要的那么多，所以我需要查看可交付成果以确保你工作足够努力。” 在这种情况下，主要问题不是文档问题。

The answer to the first question of documentation may sound something like “I need documentation because I’m afraid you don’t work as much as I’d like, so I need to see deliverables to make sure you work hard enough.” In this case, the main issue is not a matter of documentation.

正如 Matt Wynne (@mattwynne) 和 Seb Rose (@sebrose) 在 2013 年 BDD eXchange 会议上所说：“需要细节可能表明缺乏信任。” 在这样的在一个案例中，缺乏文件只是表象，根本问题是缺乏信任。这是一个足够严重的问题，你应该停止阅读这本书并尝试找到改善这种情况的方法。仅靠任何文档都无法从一开始就解决缺乏信任的问题。然而，由于交付价值通常是建立信任的好方法，因此合理的文档在补救措施中发挥着辅助作用。例如，使工作更加可见可能有助于建立信任，并且是一种文档形式。

As the duo Matt Wynne (@mattwynne) and Seb Rose (@sebrose) said at the BDD eXchange conference in 2013: “Need for detail might indicate lack of trust.” In such a case, lack of documentation is just a symptom, and the root issue is lack of trust. This is a serious enough issue that you should stop reading this book and try to find ways to improve the situation. No amount of documentation alone can fix lack of trust in the first place. However, since delivering value often is a good way to build trust, sensible documentation has a side role in a remediation. For example, making the work more visible may help build trust and is a form of documentation.

即时文档，或未来知识的廉价选择

Just-in-Time Documentation, or a Cheap Option on Future Knowledge

如果您需要文档，您可能实际上并不立即需要它。因此，还有一个文档的第一个问题。

If you need documentation, you might not actually need it right away. Hence, there is another first question of documentation.

创建文档是有成本的，而未来的收益是不确定的。当您无法确定某人将来是否需要该信息时，好处是不确定的。

Creating documentation has a cost, and the benefit in the future is an uncertain benefit. The benefit is uncertain when you cannot be sure someone will have the need for the information in the future.

多年来我在软件开发中学到的一件事是，人们在预测未来方面是出了名的糟糕。通常人们只是打赌，但他们的赌注往往是错误的。因此，使用多种策略来确定何时需要进行文档记录非常重要：

One thing I’ve learned over the years in software development is that people are notoriously bad at anticipating the future. Usually people can just bet, and their bets are often wrong. As a consequence, it is important to use a number of strategies to determine when it’s important to do documentation:

• 及时：仅在真正需要时添加文档。

• Just-in-time: Add documentation only when really needed.

• 前期成本低廉：立即添加一些文档，成本非常低。

• Cheap upfront: Add a little documentation now, at a very low cost.

• 前期费用昂贵：立即添加文档，即使创建它需要时间。

• Expensive upfront: Add documentation now, even if it takes time to create it.

质疑传统文档的必要性

Questioning the Need for Traditional Documentation

假设出于确定的目的和确定的受众确实需要额外的文档，那么您现在已经准备好处理第二个问题的文档。

Assuming that there’s a genuine need for additional documentation, for an identified purpose, and for an identified audience, you’re now ready for the second question of documentation.

传统文档永远不应该成为默认选择，因为除非绝对必要，否则太浪费了。当需要将知识从某些人转移给其他人时，最好通过简单的交谈来完成——通过提出和回答问题而不是交换书面文件。

Traditional documentation should never be the default choice, as it’s too wasteful unless absolutely necessary. When there is a need for knowledge transfer from some people to other people, this is best done by simply talking—by asking and answering questions instead of exchanging written documents.

集体工作和频繁的对话是一种特别有效的记录形式。结对编程、交叉编程、敏捷中的三个朋友和群体编程等技术完全改变了文档方面的游戏规则，因为人与人之间的知识转移是连续进行的，同时知识是在一个平台上创建或应用的。任务。

Working collectively, with frequent conversations, is a particularly effective form of documentation. Techniques such as pair programming, cross-programming, the three amigos in agile, and mob-programming totally change the game with respect to documentation, as knowledge transfer between people is done continuously and at the same time the knowledge is created or applied on a task.

对话和集体工作是首选的文档形式，尽管有时它们还不够。有时确实需要将知识形式化。

Conversations and working collectively are the preferred forms of documentation, although sometimes they are not enough. Sometime there’s a genuine need to have the knowledge formalized.

即使对于必须与大量受众共享、必须长期保留或至关重要的知识，也有多种文档选项：

Even for the knowledge that must be shared to a large audience, that must be kept persistent for the long term or that is critical, there are several documentation options:

• 全体观众出席的全体会议，或希望观众做笔记的讲座式会议演讲

• Plenary meeting with the full audience attending, or a lecture-style conference talk with the audience hopefully taking notes

• 播客或视频，例如录制的会议演讲或录制的采访

• Podcast or video, like a recorded conference talk or a recorded interview

• 自记录或通过内部文档方法增强的工件

• Artifacts that are self-documented or that are augmented in an internal documentation approach

• 手工编写的文档

• Manually written document

关键是，即使拥有特别重要的知识，手动编写文档也不一定是默认选择。

The point is that, even with particularly important knowledge, manually written documentation does not have to be the default choice.

立即减少额外工作

Minimizing Extra Work Now

假设您有合理的需要以正式的形式保留一些知识。因为，正如您所知，大多数知识已经以某种形式存在于某个地方，您需要回答另一个问题。

Say that you have a legitimate need to keep some knowledge in a formal form. Because, as you’ve learned, most knowledge already exists somewhere, in some form, you need to answer another question.

如果知识只存在于人们的头脑中，那么它需要在某个地方进行编码——作为文本、代码、元数据或其他东西。如果知识已经在某处表示，那么我们的想法是尽可能地使用它（知识利用）或重用它（知识增强）。

If knowledge is only in the heads of the people, then it needs to be encoded somewhere—as text, code, metadata, or something else. If the knowledge is already represented somewhere, the idea is to use it (knowledge exploitation) or reuse it (knowledge augmentation) as much as possible.

您也许能够使用源代码、配置文件、测试、应用程序在运行时的行为以及可能涉及的各种工具的内存中的知识。此过程将在以下章节中详细描述，涉及提出以下问题：

You might be able to use the knowledge that’s in the source code, in the configuration files, in the tests, in the behavior of the application at runtime, and perhaps in the memory of the various tools involved. This process, which is described in detail in the following chapters, involves asking the following questions:

• 这些知识是可利用的，还是被混淆的，或者是不可恢复的？

• Is the knowledge exploitable, or obfuscated, or unrecoverable?

• 知识太丰富了吗？

• Is the knowledge too abundant?

• 目标受众是否可以获取这些知识？

• Is the knowledge accessible for the intended audience?

• 知识是集中在一个地方还是分散的？

• Is the knowledge in one single place or fragmented?

• 缺少什么才能使知识 100% 明确？

• What is missing that would make the knowledge 100% explicit?

当知识不完全存在或太隐晦而无法使用时，游戏就变成寻找一种将知识直接添加到产品源中的方法。这是第 4 章“知识增强”的重点。

When the knowledge is not fully there or is too implicit to be used, then the game becomes finding a way to add the knowledge directly into the source of the product. That is the focus of Chapter 4, “Knowledge Augmentation.”

最大限度地减少以后的额外工作

Minimizing Extra Work Later

仅创建一次文档是不够的；还要创建文档。您必须考虑如何随着时间的推移保持其准确性。因此，仍然存在一个重要的问题。

It’s not enough to create documentation once; you must consider how to keep it accurate over time. Therefore, an important question remains.

稳定的知识很容易，因为你可以忽略它的维护问题。另一方面，生活知识具有挑战性。它可以经常或随时更改，并且您不希望一遍又一遍地更新多个工件和文档。

Stable knowledge is easy because you can ignore the question of its maintenance. On the other end of the spectrum, living knowledge is challenging. It can change often or at any time, and you don’t want to update multiple artifacts and documents over and over.

变化率是关键标准（见图1.10）。多年来稳定的知识可以用任何传统形式来处理，例如手动书写文本并将其打印在纸上。多年稳定的知识甚至可以在一定程度的重复中幸存下来，因为它不需要更新。

The rate of change is the crucial criterion (see Figure 1.10). Knowledge that is stable over years can be taken care of with any traditional form, such as writing text manually and printing it on paper. Knowledge that is stable over years can even survive some amount of duplication because it will not need to be updated.

相比之下，每小时或更频繁地变化的知识无法承受传统形式的文档。要记住的关键问题是演化成本和维护文档的成本。更改源代码然后必须手动更新其他文档不是一种选择。

In contrast, knowledge that changes every hour or more often just cannot afford traditional forms of documentation. The key concerns to keep in mind are the cost of evolution and the cost of maintaining the documentation. Changing the source code and then having to update other documents manually is not an option.

这个过程将在接下来的章节中描述，涉及以下问题：

This process, which is described in the next chapters, involves the following questions:

• 如果改变，同时改变什么？

• If it changes, what changes at the same time?

• 如果存在冗余知识，我们如何保持冗余源同步？

• If there’s redundant knowledge, how do we keep the redundant sources in sync?

活文档：非常简短的版本

Living Documentation: The Very Short Version

如果您只想花一点时间了解活文档的全部内容，请记住以下重要想法：

If you only want to spend a minute on what living documentation is all about, please remember the following big ideas:

• 喜欢在各种文档上进行对话和合作。大多数知识已经存在，只是需要挣脱束缚。

• Favor conversations and working together over every kind of document. Most knowledge is already there and just needs to break free.

• 大多数知识已经在那里了。您只需要补充缺失的上下文、意图和基本原理即可。

• Most of the knowledge is there already. You just need to augment it with the missing context, intent, and rationale.

• 注意变化的频率。

• Pay attention to the frequency of change.

• 考虑文档是一种引起人们对系统质量或缺乏质量的关注的方法。

• Thinking about documentation is a way to draw attention to the quality or lack thereof in a system.

如果这个列表足够清晰，那么您就已经理解了本章的关键信息。

If this list is clear enough, you’ve understood the key message of this chapter.

更好的文档编制方法

Approaches to Better Documentation

有很多方法可以考虑文档主题。这些方法涵盖了整个范围，可以被视为一个循环，遵循从避免文档到最大程度的文档，然后再到进一步的进展。再次质疑是否需要文档，并再次循环到更少的文档。您还可以将这个周期视为从轻量级方法到更重量级的方法。

There are many ways to consider the topic of documentation. These approaches cover a full spectrum that can be seen as a cycle that follows a progression from avoiding documentation to documentation to the max and then beyond, to questioning the need for documentation again and looping the cycle to less documentation again. You could also see this cycle as going from lightweight approaches to more heavyweight ones.

这个循环涉及相关知识的变化率（波动性），从稳定的知识到不断变化的知识。

This cycle involves the rate of change (volatility) of the knowledge in question, from stable knowledge to knowledge that changes continuously.

下面描述了以下类别的文档方法，这些方法将在本书中进行讨论：

The following describes the following categories of approaches to documentation, which are discussed throughout this book:

• 避免文档：最好的文档通常是没有文档，因为除了工作之外，知识不值得任何特别的努力。对话或集体工作的协作是这里的关键。有时，您可以做得更好并改善潜在的情况，而不是通过文档来解决它。例子包括自动化和解决根本问题。

• Avoiding documentation: The best documentation is often no documentation because the knowledge is not worth any particular effort beyond doing the work. Collaboration with conversation or collective work is key here. Sometimes you can do even better and improve the underlying situation rather than work around it with documentation. Examples include automation and fixing the root issues.

• 稳定的文档：并非所有知识都会不断变化。当它足够稳定时，文档就会变得更加简单，同时也更加有用。有时，从改变一种知识到一种更稳定的知识只需要一步——这就是你想要利用的机会类型。

• Stable documentation: Not all knowledge changes all the time. When it’s stable enough, documentation becomes much simpler and much more useful at the same time. Sometimes it just takes one step to go from changing a piece of knowledge to a more stable one—and this is the type of opportunity you want to exploit.

• 可重构文档：由于现代 IDE 和工具的重构功能，代码、测试、纯文本等提供了持续同步发展的特殊机会。可重构的文档使准确的文档成为可能，并且几乎不需要任何成本。

• Refactorable documentation: Code, tests, plain text, and so on present particular opportunities to evolve continuously in sync, thanks to the refactoring capabilities of modern IDEs and tools. Refactorable documentation makes possible accurate documentation for little to no cost.

• 自动化文档：自动化文档是最极客的领域，涉及使用特定的工具以生动的方式自动生成文档，跟随软件构造的变化。自动化文档的一种特殊风格涉及在软件运行时运行的每种方法；这与在构建时起作用的其他方法形成对比。

• Automating documentation: Automating documentation is the geekiest area, involving using specific tools to produce documentation automatically in a living fashion, following the changes in the software construction. A particular flavor of automating documentation involves every approach that operates at runtime, when the software is running; this is in contrast to other approaches that work at build time.

• 超越文档：最后，我们到达了超越文档领域，在这里我们有机会质疑一切，并认识到文档主题的好处远远超出了仅仅传输和存储知识。这是我们获得启示并以更批判的方式重新考虑所有其他方法和技术的地方。活文档的这一方面比较抽象，但很重要。通过活文档实践来激发您对工作的注意力，从而提高工作质量。

• Beyond documentation: Finally, we reach the beyond documentation area, where we have the opportunity to question everything and recognize that the topic of documentation can have benefits well beyond just transferring and storing knowledge. This is where we reach enlightenment and reconsider every other approach and technique in a more critical way. This aspect of living documentation is more abstract, but important. Through living documentation practices that stimulate your attention to your work, the quality of the work can be improved as a side effect.

这些类别构成了本书的主要章节，但顺序相反，从更技术性和更容易掌握到更抽象以及以人为本的考虑。这种顺序意味着章节从不太重要到更重要。

These categories structure the main chapters of this book—but in reverse order to follow a progression from more technical and rather easy-to-grasp to more abstract and people-oriented considerations. This ordering means the chapters progress from the less important to the more important.

在这些方法类别中，本书讨论了一些核心原则，指导您如何有效地进行文档编制。

Across these categories of approaches, this book discusses some core principles that guide you in how to do documentation efficiently.

简而言之，领域驱动设计

Domain-Driven Design in a Nutshell

领域驱动设计是一种解决软件开发核心复杂性的方法。它主要主张重点关注正在考虑的特定业务领域。它提倡编写从字面上表达领域知识的代码，而无需在领域分析和可执行代码之间进行翻译。因此，与许多有关建模的文献相反，它要求直接在用编程语言编写的代码中进行建模。只有能够与领域专家进行频繁且密切的对话，并且每个人都使用相同的普遍语言（业务领域的语言），这才有可能实现。

Domain-driven design is an approach to tackling complexity in the heart of software development. It primarily advocates a sharp focus on the particular business domain being considered. It promotes writing code that expresses the domain knowledge literally, with no translation between the domain analysis and the executable code. As such, it calls for modeling directly in code written in a programming language, in contrast with a lot of literature on modeling. This is possible only if there is the possibility of frequent and close conversations with domain experts, with everyone using the same ubiquitous language—the language of the business domain.

领域驱动设计要求将精力集中在核心领域，即有潜力在竞争中发挥作用的业务领域。因此，DDD 鼓励开发人员不仅交付代码，而且作为业务合作伙伴以建设性的双向关系做出贡献，在这种关系中，开发人员可以深入了解业务并深入了解重要的利害关系。

Domain-driven design calls for focusing the efforts on the core domain, the one business area with the potential to make a difference against the competition. As such, DDD encourages developers not just to deliver code but to contribute as partners with the business in a constructive two-way relationship where the developers grow a deep understanding of the business and gain insights into the important stakes.

领域驱动设计深深植根于 Kent Beck 的《极限编程解释：拥抱变化》。它也建立在模式文献之上，最著名的是 Martin Fowler 的《分析模式：可重用对象模型》和 Rebecca Wirfs-Brock 的《对象设计：角色、责任和协作》，这本书开始了“xDD”命名的实践。

Domain-driven design is deeply rooted in Kent Beck’s Extreme Programming Explained: Embrace Change. It is also built on top of the pattern literature, most notably Martin Fowler’s Analysis Patterns: Reusable Object Models and Rebecca Wirfs-Brock’s Object Design: Roles, Responsibilities, and Collaborations, the book that began the practice of “xDD” naming.

Eric Evans 的《领域驱动设计：解决软件核心的复杂性》还包含许多成功应用 DDD 的模式。最重要的概念之一是有界上下文的概念。有界上下文定义系统中语言可以保持精确且没有歧义的区域。有界上下文是对系统设计的重大贡献；它们将大型、复杂的系统简化并划分为几个更小、更简单的子系统——没有太大的缺点。在团队之间有效地分割系统和工作是相当困难的，有界上下文的概念是一个强大的设计工具，可以帮助解决这个问题。

Eric Evans’s Domain-Driven Design: Tackling Complexity in the Heart of Software also includes numerous patterns for applying DDD successfully. One of the most important concepts is the notion of bounded context. A bounded context defines an area of a system where the language can be kept precise and without ambiguity. Bounded contexts are a major contribution to system design; they simplify and partition large, complicated systems into several smaller and simpler subsystems— without much downside. Splitting systems and work between teams efficiently is quite hard, and the notion of bounded contexts is a powerful design tool to help with this.

由于 Evans 的《领域驱动设计》一书于 2003 年出版，其中的大多数示例都是针对面向对象编程语言中的应用而提出的，但从那时起，人们已经清楚 DDD 也同样适用于函数式编程语言。我经常声称 DDD 提倡函数式编程风格的代码，即使在面向对象的编程语言中也是如此。

Because Evans’s Domain-Driven Design book was published in 2003, most of its  examples were proposed for application in object-oriented programming languages, but it has become clear since then that DDD applies just as well with functional programming languages. I often make the claim that DDD advocates a functional programming style of code even in object-oriented programming languages.

实时文档和领域驱动设计

Living Documentation and Domain-Driven Design

本书重点讨论了 DDD 的几个方面：

This book focuses on several aspects of DDD:

• 它促进了 DDD 在项目中的使用，特别是通过所选示例。

• It promotes the use of DDD in a project, in particular through the chosen examples.

• 它展示了文档如何支持 DDD 的采用以及它如何充当反馈机制来改进您的实践。

• It shows how documentation can support the adoption of DDD and how it can act as a feedback mechanism to improve your practice.

• 它本身就是 DDD 在文档和知识管理主题上的应用，以处理该主题的方式。

• It is in itself an application of DDD on the subject of documentation and knowledge management, in the way this topic is approached.

• 特别是，活文档的许多实践实际上直接来自 Eric Evans 书中的 DDD 模式。

• In particular, many of the practices of living documentation are actually directly DDD patterns from Eric Evans’s book.

• 写这本书的目的是通过文档实践来真正引起人们对设计或缺乏设计的关注，当团队的设计工作做得很差时，这些实践会让人们注意到这一点。

• The point of writing this book is to actually draw attention to design, or lack of thereof, through documentation practices that make it visible when the team is doing a poor job of design.

这些因素是否使这本书成为一本关于 DDD 的书？我想是这样。作为 DDD 的粉丝，我肯定会喜欢这样的情况。

Do these factors make this book a book on DDD? I think so. As a fan of DDD, I would definitely love this to be the case.

活文档就是让每个决策变得明确，不仅包括代码中的后果，还包括使用代码作为文档媒介的所有表现力来表达（或可能建模）的基本原理、上下文和相关业务利益。

Living documentation is all about making each decision explicit, with not only the consequences in code but also the rationale, the context, and the associated business stakes expressed (or perhaps modeled) using all the expressiveness of the code as a documentation medium.

如果一个项目解决了没有标准解决方案的问题，那么它就是有趣的。该项目必须在探索领域时通过不断学习和大量知识消化来发现如何解决问题。因此，生成的代码会一直发生变化，从小的变化到重大的突破。

A project is interesting if it addresses a problem for which there is no standard solution. The project must discover how to solve the problem through continuous learning and a lot of knowledge crunching while exploring the domain. As a consequence, the resulting code will change all the time, from small changes to major breakthroughs.

“尝试，再试一次”需要易于更改的文档。然而，无论何时，保留花费大量精力学习的宝贵知识都很重要。一旦掌握了知识，您就可以通过编写和重构源代码和其他技术工件将其转化为有价值且可交付的软件。但你需要找到方法在这个过程中保留知识。

“Try, Try Again” requires change-friendly documentation. However, at all times it is important to keep the precious knowledge that took so much effort to learn. Once the knowledge is there, you can turn it into valuable and deliverable software by writing and refactoring source code and other technical artifacts. But you need to find ways to keep the knowledge through this process.

DDD提倡“用代码建模”作为根本解决方案。这个想法是代码本身就是知识的表示。只有当代码不够用时才需要别的东西。战术模式利用了代码是主要媒介的理念，它们指导开发人员如何使用普通的编程语言在实践中使用它。

DDD advocates “modeling with code” as the fundamental solution. The idea is that code itself is a representation of the knowledge. Only when the code is not enough do you need something else. Tactical patterns leverage the idea that code is the primary medium, and they guide developers in how to use it as such in practice, with their ordinary programming language.

因此：您对学习实时文档的投资也是对学习领域驱动设计某些方面的投资。学一个，就可以免费学习另一个的一半！

Therefore: Your investment in learning living documentation is also an investment in learning some aspects of domain-driven design. Learn one, and you learn half of the other for free!

当活文档成为 DDD 的应用时

When Living Documentation Is an Application of DDD

活文档不仅支持 DDD，而且本身就是将 DDD 方法应用于知识整个生命周期管理领域的示例。在许多情况下，活文档是 DDD 的直接应用案例，但名称略有不同。

Living documentation not only supports DDD but is also in itself an example of applying the DDD approach on the domain of managing knowledge throughout its lifecycle. And in many cases, living documentation is a directly applied case of DDD under a slightly different name.

BDD、DDD、XP 和活文档之间相互根源的故事

A Story of Mutual Roots Between BDD, DDD, XP, and Living Documentation

活文档这个术语是由 Gojko Adzic 在《Specification by Example》中引入的，这是一本关于行为驱动开发 (BDD) 的书。BDD 是 Dan North 提出的一种涉及参与软件开发的每个人之间协作的方法，他通过将测试驱动开发 (TDD) 与领域驱动设计的通用语言相结合来引入这一想法。因此，甚至“活文档”这个术语也已经植根于领域驱动设计！

The term living documentation was introduced by Gojko Adzic in Specification by Example, which is a book on behavior-driven development (BDD). BDD is an approach involving collaboration between everyone involved in software development that was proposed by Dan North, who introduced the idea by combining test-driven development (TDD) with the ubiquitous language of domain-driven design. As a consequence, even the term living documentation already has roots in domain-driven design!

考虑到活文档强烈遵循 DDD 的以下原则：

Consider that living documentation strongly adheres to the following tenets of DDD:

• 代码即模型：代码就是模型（反之亦然），因此您希望在代码中尽可能多地了解模型——根据定义，这就是文档。

• Code as the model: Code is the model (and vice versa), so you want to have as much knowledge of the model in the code as possible—and this is, by definition, the documentation.

• 使代码表达所有知识的战术技术：您希望最大限度地利用编程语言可以表达的内容，甚至表达不在运行时执行的知识。

• Tactical techniques to make the code express all the knowledge: You want to exploit programming languages to the maximum of what they can express, to express even knowledge that is not executed at runtime.

• 通过 DDD 漩涡不断发展知识：知识处理主要是业务领域专家和开发团队之间的协作问题。通过这个过程，一些最重要的知识会体现在代码中，也许还会体现在其他一些工件中。由于所有知识都会不断发展或随时可能发展，因此任何记录在案的知识都必须拥抱变化，而不会遇到维护成本等障碍。

• Evolving the knowledge all the time with the DDD whirlpool: Knowledge crunching is primarily a matter of collaboration between business domain experts and the development team. Through this process, some of the most important knowledge becomes embodied into the code—and perhaps into some other artifacts. Because all the knowledge evolves or may evolve at any time, any documented knowledge must embrace change without impediments such as maintenance costs.

• 明确什么是重要的，什么是不重要的：换句话说，需要关注策划。“专注于核心领域”和“突出核心概念”来自 Evans 的 DDD 书中，但尽管人类的记忆和认知能力有限，但您可以通过管理做更多事情来帮助控制知识。

• Making clear what’s important and what’s not: In other words, there needs to be a focus on curation. “Focus on the core domain” and “highlight the core concepts” are from Evans’s DDD book, but there’s much more you can do with curation to help keep the knowledge under control despite the limited human memory and cognition capabilities.

• 关注细节：许多 DDD 模式强调关注细节很重要。决策应该经过深思熟虑，而不是武断，并且应该以具体反馈为指导。动态记录方法必须通过更轻松地记录有意的内容并在整个过程中提供富有洞察力的反馈来鼓励对细节的关注。

• Attention to detail: Many DDD patterns emphasize that attention to detail is important. Decisions should be deliberate and not arbitrary, and they should be guided by concrete feedback. The living documentation approach has to encourage attention to detail by making it easier to document what’s deliberate and by giving insightful feedback throughout the process.

• 战略设计和大规模结构： DDD 提供了在战略层面和大规模上处理不断变化的知识的技术，也为更智能的文档提供了机会。

• Strategic design and large-scale structures: DDD offers techniques to deal with evolving knowledge at the strategic level and on a large scale, providing opportunities for smarter documentation, too.

如果不重写其他书籍的部分内容，就很难提及活文档和领域驱动设计的思想之间的所有对应关系。但需要一些例子来说明这一点（见表1.2）。

It is difficult to mention all the correspondences between the ideas of living documentation and domain-driven design without rewriting parts of other books. But some examples are necessary to make the point (see Table 1.2).

表1-2 Living Documentation与DDD的对应关系

Table 1-2 Correspondence Between Living Documentation and DDD

活文档超越了传统文档及其局限性。它详细阐述了 DDD 技术和有关业务领域知识的建议，以及有关设计、基础设施和交付流程的知识，对于项目利益相关者来说，这些知识也是技术领域。领域驱动设计的思想对于指导开发人员如何以战术和战略方式投资知识、应对短期和长期的变化至关重要。因此，当您走活文档路线时，您也在学习领域驱动设计。

Living documentation goes beyond traditional documentation and its limitations. It elaborates on the DDD techniques and advice for knowledge about the business domain and also for knowledge about the design, as well as the infrastructure and delivery process, which are technical domains, too, with respect to the project stakeholders. The ideas from domain-driven design are essential to guiding developers in how to invest in knowledge in a tactical and strategic way, dealing with change in the short term and in the long term as well. Therefore, as you are going the living documentation route, you are learning domain-driven design, too.

冗余与协调

Redundancy and Reconciliation

BDD场景描述了应用程序的行为，但应用程序的源代码也描述了这种行为：场景和源代码是相互冗余的，如图2.2所示。

BDD scenarios describe the behavior of an application, but the source code of the application also describes this behavior: The scenarios and source code are redundant with each other, as shown in Figure 2.2.

一方面，这种冗余是个好消息：如果处理得当，用纯领域语言表达的场景对于非技术受众（例如永远无法阅读代码的业务人员）来说是可以访问的。然而，这种冗余也是一个问题：如果某些场景或部分代码独立演化，那么你就会遇到两个问题：你必须确定是否信任这些场景或代码，并且（一个更大的问题），你必须以某种方式知道场景和代码不同步。

On one hand, this redundancy is good news: Scenarios expressed in pure domain language, if done properly, are accessible to nontechnical audiences such as business people who could never read code. However, this redundancy is also a problem: If some scenarios or parts of the code evolve independently, then you have two problems: You must determine whether to trust the scenarios or the code, and (a bigger problem), you must in some way know that the scenarios and the code are not in sync.

这就是需要协调机制的地方。对于 BDD，您可以使用 Cucumber 或 SpecFlow 等测试和工具。这些工具的作用就像是两个冗余知识之间的 Roberval 平衡，如图2.3所示。

This is where a reconciliation mechanism is needed. In the case of BDD, you can use tests and tools like Cucumber or SpecFlow. These tools act like a Roberval balance between both redundant pieces of knowledge, as pictured in Figure 2.3.

这些工具以纯文本形式解析场景，并使用开发人员提供的一些粘合代码来驱动实际代码。调用实际代码时，将提取场景的“Given”和“When”部分中的金额、日期和其他值并将其作为参数传递。另一方面，从场景的“Then”部分提取的值用于断言，以根据代码匹配的结果检查场景中的预期内容。

These tools parse the scenarios in plain text and use some glue code provided by the developers to drive the actual code. The amounts, dates, and other values in the “Given” and “When” sections of the scenarios are extracted and passed as parameters when calling the actual code. The values extracted from the “Then” sections of the scenarios, on the other hand, are used for the assertions, to check what’s expected in the scenario, based on the result from the code matches.

这些工具将场景转变为自动化测试。好处是这些测试还提供了一种方法来检测场景和代码何时不再同步。这是协调机制的一个示例，这是一种确保冗余信息集始终匹配的方法。

The tools turn scenarios into automated tests. The nice thing is that these tests also provide a way to detect when the scenarios and the code are no longer in sync. This is an example of a reconciliation mechanism, a means to ensure that redundant sets of information always match.

功能文件的意图

The Intent of a Feature File

功能文件必须以描述文件中所有场景的意图的叙述开始。它通常遵循“为了……”的模式。作为一个…。我想要……”以“为了”开头可以帮助您专注于最重要的事情：您正在寻找的价值。

A feature file must start with a narrative that describes the intent of all the scenarios in the file. It usually follows the pattern “In order to…. As a…. I want.…” Starting with “In order to” helps you focus on the most important thing: the value you’re looking for.

以下是关于在包裹递送车队管理背景下检测潜在欺诈的应用程序的叙述示例：

Here’s an example of a narrative for an application about detection of potential frauds in the context of fleet management for parcel delivery:

点击这里查看代码图片

Click here to view code image

1 特征：加油卡交易异常
2 为了检测潜在的加油卡异常行为
司机
3 作为车队经理
4 我想自动检测所有加油卡的异常情况
交易

1  Feature: Fuel Card Transactions anomalies
2  In order to detect potential fuel card abnormal behavior by
drivers
3  As a fleet manager
4  I want to automatically detect anomalies in all fuel card
transactions

请注意，这些工具仅将叙述视为文本；除了将其包含在报告中之外，他们不会对它做任何事情，因为他们承认它很重要。

Note that the tools just consider the narrative as text; they don’t do anything with it except include it in the reports because they acknowledge that it’s important.

特征文件场景

Feature File Scenarios

功能文件的其余部分通常列出与相应功能相关的所有场景。每个场景都有一个标题，并且场景几乎总是遵循“鉴于……”。什么时候…。然后……”模式。

The rest of the feature file usually lists all the scenarios that are relevant for the corresponding feature. Each scenario has a title, and scenarios almost always follow the “Given…. When…. Then…” pattern.

以下是在包裹递送车队管理背景下检测潜在欺诈的应用程序的众多具体场景之一的示例：

Here’s an example of one of the many concrete scenarios for an application on detection of potential frauds, in the context of fleet management for parcel delivery:

点击这里查看代码图片

Click here to view code image

1 场景：油量多于车辆的油量交易
坦克可以容纳
2 假设车辆 23 的油箱尺寸为 48L
3 加油卡上报告 52L 交易时
4 与车辆 23 相关
5 然后出现异常“52L的燃油交易超过油箱
据报道尺寸为48L”

1  Scenario: Fuel transaction with more fuel than the vehicle
tank can hold
2  Given that the tank size of the vehicle 23 is 48L
3  When a transaction is reported for 52L on the fuel card
4  associated with vehicle 23
5  Then an anomaly "The fuel transaction of 52L exceeds the tank
size of 48L" is reported

在一个功能文件中，通常有 3 到 15 个场景，描述快乐路径、其变体以及最重要的情况。

Within one feature file there are typically between 3 and 15 scenarios, describing the happy path, its variants, and the most important situations.

还有许多其他方法可以描述场景，例如使用大纲格式，并且还有一些方法可以分解场景与背景场景之间的共同假设。（有关大纲格式和背景场景的更多信息，请参阅https://docs.cucumber.io/gherkin/reference/。）

There are a number of other ways to describe scenarios, such as by using the outline format, and there are also ways to factor out common assumptions between scenarios with background scenarios. (For more information on outline format and background scenarios, see for example https://docs.cucumber.io/gherkin/reference/.)

规格详情

Specification Details

在很多情况下，仅场景就足以描述预期的行为，但在一些丰富的业务领域，例如会计或金融，场景肯定是不够的。在这种情况下，您还需要抽象的规则和公式。

There are many cases in which scenarios alone are enough to describe the expected behavior, but in some rich business domains, such as accounting or finance, scenarios are definitely not enough. In such cases, you also need abstract rules and formulas.

您无需将所有这些附加知识放入 Word 文档或 wiki 中，而是可以直接将其嵌入到相关功能文件中的意图和场景列表之间。这是一个示例，来自与之前相同的功能文件：

Rather than putting all this additional knowledge in a Word document or in a wiki, you can directly embed it within the related feature file, between the intent and the list of scenarios. Here’s an example, from the same feature file as before:

点击这里查看代码图片

Click here to view code image

1 特征：加油卡交易异常
2 为了检测潜在的加油卡异常行为
司机
3 作为车队经理
4 我想自动检测所有加油卡的异常情况
交易
5
6 说明：
7 监控检测到以下异常情况：
8 * 燃油泄漏：只要容量 > 1 + 公差，
9 其中容量=交易燃油数量/车辆油箱尺寸
10 * 交易距离车辆太远：每当距离
车辆 > 阈值，
11 其中到车辆的距离 = 地理距离（车辆
坐标，气体
12个站坐标），
13、其中车辆坐标由GPS提供
14 跟踪（车辆、时间戳）、
15 加油站坐标由以下提供：
16对其邮寄地址进行地理编码。
17 号
18 场景：燃料交易无异常
19 当加油卡上报告交易时
20 .../// 这里有更多场景

1  Feature: Fuel Card Transactions anomalies
2  In order to detect potential fuel card abnormal behavior by
drivers
3  As a fleet manager
4  I want to automatically detect anomalies in all fuel card
transactions
5
6  Description:
7  The monitoring detects the following anomalies:
8  * Fuel leakage: whenever capacity > 1 + tolerance,
9  where capacity = transaction fuel quantity / vehicle tank size
10 * Transaction too far from the vehicle: whenever distance to
vehicle > threshold,
11 where distance to vehicle = geo-distance (vehicle
coordinates, gas
12 station coordinates),
13 and where the vehicle coordinates are provided by the GPS
14 Tracking by (vehicle, timestamp),
15 and where the gas station coordinates are provided by
16 geocoding its post address.
17
18 Scenario: Fuel transaction with no anomaly
19 When a transaction is reported on the fuel card
20 .../// more scenarios here

这些规范细节只是作为自由文本的注释；工具完全忽略它。然而，把它放在那里的目的是与相应的场景共存。每当您更改场景或细节时，您更有可能更新规范细节，因为它们非常接近。正如我们所说，“眼不见心不烦”。但并不能保证这样做。

These specification details are just comments as free text though; the tools completely ignore it. However, the point of putting it there is to have co-located with the corresponding scenarios. Whenever you change the scenarios or the details, you are more likely to update the specification details because they are so close. As we say, “out of sight, out of mind.” But there is no guarantee to do so.

特征文件中的标签

Tags in Feature Files

功能文件中的最后一个重要组成部分是添加标签的能力。每个场景都可以有标签，如下所示：

The last significant ingredient in feature files is the ability to add tags. Each scenario can have tags, like the following:

点击这里查看代码图片

Click here to view code image

1 @acceptance-criteria @specs @wip @fixedvenue @interests
2 场景：一年内的双年复利
3 假设本金为 1000 美元
4 ...//

1  @acceptance-criteria @specs @wip @fixedincome @interests
2  Scenario: Bi-annual compound interests over one year
3  Given a principal of USD 1000
4  ...//

标签是文档。有些标签描述了项目管理知识，例如@wip，它代表正在进行的工作并表示该场景当前正在开发。其他类似的标签甚至可能会命名参与开发的人员（例如@bob、@team-red）或提及冲刺（例如@sprint-23）或其目标（例如@learn-about-reporting-需要）。这些标签是临时的，任务完成后将被删除。

Tags are documentation. Some tags describe project management knowledge, such as @wip, which stands for work in progress and signals that this scenario is currently being developed. Other similar tags may even name who’s involved in the development (for example, @bob, @team-red) or mention the sprint (for example, @sprint-23) or its goal (for example, @learn-about-reporting-needs). These tags are temporary and are deleted when the tasks are all done.

有些标签描述了场景的重要性。例如，@acceptance-criteria 表示此场景是少数用户接受标准的一部分。其他类似的标签可能有助于场景的策划，例如 @happy-path、@nominal、@variant、@negative、@exception 和 @core。

Some tags describe how important the scenario is. For example, @acceptance-criteria indicates that this scenario is part of the few user acceptance criteria. Other similar tags may help with curation of scenarios, such as @happy-path, @nominal, @variant, @negative, @exception, and @core.

最后，一些标签描述了业务领域的类别和概念。例如，在刚刚显示的示例中，标签@fixedvenue和@interests描述了该场景与固定收益和利息金融领域相关。

Finally, some tags describe categories and concepts from the business domain. For example, in the example just shown, the tags @fixedincome and @interests describe that this scenario is relevant to the fixed income and interest financial areas.

标签也应该被记录下来。例如，并置文本文件可以列出所有有效标签以及每个标签的文本描述。为了确保功能文件中使用的每个标签都记录在那里，我的同事 Arnauld Loyer 喜欢添加一个单独的单元测试作为另一种协调机制。

Tags should be documented, too. For example, a collocated text file can list all the valid tags, along with a text description for each. And to make sure that every tag used in the feature files is documented there, my colleague Arnauld Loyer likes to add a separate unit test as yet another reconciliation mechanism.

场景作为互动活文档

Scenarios as Interactive Living Documentation

这些场景构成了活文档的基础。更好的是，该文档通常是交互式的，作为生成的交互式网站。例如，如果您使用 Pickles for SpecFlow，每次构建期间都会生成一个特定的单页网站（见图2.4）。该网站会显示按章节组织的导航窗格，前提是您的文件夹代表功能章节。它显示所有场景以及测试结果及其统计数据。这非常强大——比您见过的任何纸质文档都要强大得多。

The scenarios form the basis for living documentation. Even better, this documentation is typically interactive, as a generated interactive website. For example, if you use Pickles for SpecFlow, a specific one-page website is generated during each build (see Figure 2.4). The website shows a navigation pane that is organized by chapter, provided that your folders represent functional chapters. It displays all scenarios, together with the test results and their statistics. This is quite powerful—much more so than any paper documentation you’ve ever seen.

Pickles 中的内置搜索引擎允许通过关键字或标签即时访问任何场景。这是标签的第二个强大作用：它们使搜索更加高效和准确。

A built-in search engine in Pickles allows instant access to any scenario by keyword or by tag. This is the second powerful effect of tags: They make searching more efficient and accurate.

无聊的纸质文档中的场景

Scenarios in Boring Paper Documents

像上一节所示的交互式网站对于团队来说很方便，可以快速访问业务行为知识。然而，在某些情况下，例如当存在强制性合规性要求时，您必须提供无聊的纸质文档（有些人称之为“BPD”）。

An interactive website like the one shown in the preceding section is convenient for a team, providing fast access to the business behavior knowledge. However, in some cases, such as when there are mandatory compliance requirements, you must provide a boring paper document (a “BPD,” as some call it).

有用于创建这些文档的工具。其中一个是由我的 Arolla 同事 Arnauld Loyer (@aloyer) 开发的，称为 Tzatziki ¹，因为它是一种黄瓜酱。它从功能文件中导出一个漂亮的 PDF 文档。它更进一步，还包括与功能文件一起存储到文档中的 Markdown 文件和图像。因此，它有助于在每个功能区域章节的开头创建很好的解释。

There are tools for creating these documents. One of them, which was developed by my Arolla colleague Arnauld Loyer (@aloyer), is called Tzatziki¹, because it’s a Cucumber sauce. It exports a beautiful PDF document out of the feature files. It goes a bit further, also including Markdown files and images that are stored alongside the feature files into the document. It therefore helps create nice explanations at the beginning of each functional area chapter.

1. Tzatziki， https://github.com/Arnauld/tzatziki

1.Tzatziki, https://github.com/Arnauld/tzatziki

BDD 是活文档的一个很好的例子：它不是需要完成的额外工作，而是正确工作的一部分。由于充当协调机制的工具，它始终保持同步。如果源代码中的功能文件还不够，生成的网站将说明文档如何变得有用、交互式、可搜索和组织良好。

BDD is a great example of living documentation: It’s not additional work to be done but is part of doing work properly. It’s always in sync, thanks to the tools that act as reconciliation mechanisms. And if the feature files in the source code are not enough, the generated website illustrates how documentation can be useful, interactive, searchable, and well organized.

基于属性的测试和 BDD

Property-Based Testing and BDD

要求通常作为属性自然而然地出现（例如，“支付和收到的所有金额的总和必须始终为零”或“没有人可以同时成为律师和法官”）。在进行 BDD 或 TDD 时，必须将这些通用属性阐明为具体的具体示例，这将有助于发现问题并逐步构建代码。

Requirements often come naturally as properties (for example, “The sum of all amounts paid and received must be zero at all times” or “Nobody can ever be a lawyer and a judge at once”). When doing BDD or TDD, you must clarify these general properties into specific concrete examples, which will help with finding issues and building code incrementally.

跟踪一般属性以了解其文档价值是个好主意。您通常在功能文件中以纯文本注释的形式执行此操作，如本章前面所述。但碰巧的是，基于属性的测试技术正是针对随机生成的样本来运用这些属性。这是通过基于属性的测试框架执行的，该框架一遍又一遍地运行相同的测试，并使用样本生成器生成的输入。规范的框架是 Haskell 中的 QuickCheck，现在大多数其他编程语言中都有类似的工具。

It’s a good idea to keep track of the general properties for their documentation value. You usually do that as plain text comments in the feature file, as described earlier in this chapter. But it happens that the technique of property-based testing is precisely about exercising these properties against randomly generated samples. This is performed with a property-based testing framework that runs the same test over and over, with inputs generated from generators of samples. The canonical framework is QuickCheck in Haskell, and there are now similar tools in most other programming languages.

将基于属性的测试集成到功能文件中最终也使常规属性也可执行。在实践中，只需添加描述通用属性的特殊场景并调用下面基于属性的测试框架，如下所示：

Integrating property-based testing into your feature files eventually makes the general properties executable, too. In practice, it’s a matter of adding special scenarios describing the general property and invoking the property-based testing framework underneath, as shown here:

点击这里查看代码图片

Click here to view code image

1 场景：所有兑换的现金金额之和必须为零
对于衍生品
2
3 给定任何衍生金融工具
4 以及其生命周期内的随机日期
5 当我们在该日产生相关现金流量时
付款人和\
6 接收器
7 那么付款人和接收人的现金流量之和
是\
8 恰好为零

1 Scenario: The sum of all cash amounts exchanged must be zero
for derivatives
2
3  Given any derivative financial instrument
4  And a random date during its lifetime
5  When we generate the related cash flows on this date for the
payer and\
6  the receiver
7  Then the sum of the cash flows of the payer and the receiver
is\
8  exactly zero

此类场景通常使用诸如“给定任何购物车......”之类的句子。这种措辞对于常规场景来说是一种代码味道，但对于补充常规具体场景的基于属性的测试工具之上的面向属性的场景来说是可以的。

Such scenarios typically use sentences like “given ANY shopping cart….” This wording is a code smell for regular scenarios, but it’s okay for property-oriented scenarios on top of property-based testing tools supplementing the regular concrete scenarios.

1 https://en.wikipedia.org/wiki/Present_value

1  https://en.wikipedia.org/wiki/Present_value

1 go/search?q=当前+值

1  go/search?q=present+value

1 https://en.wikipedia.org/w/index.php?search=present+value

1  https://en.wikipedia.org/w/index.php?search=present+value

生成已发布文档的一些示例

Some Examples of Producing a Published Document

有许多工具可用于根据源代码和其他技术工件生成文档。这里有些例子：

There are many tools available to produce documents out of source code and other technical artifacts. Here are some examples:

• GitHub： GitHub 采用 README.md 文件（该文件是有关整个项目目标的单一知识来源），并将其转换为呈现为漂亮的网页。

• GitHub: GitHub takes the README.md file, which is a single source of knowledge about the goals of an overall project, and turns it into a web page that is rendered to be pretty.

• Javadoc： Javadoc 提取代码的结构以及所有公共或私有 API，并将其作为参考文档发布到网站。您可以轻松地基于标准 Javadoc Doclet 创建自定义工具，以生成您自己的特定报告、术语表或图表，如第 6 章“自动化文档”中所述。

• Javadoc: Javadoc extracts the structure and all the public or private API of the code and publishes it to a website as reference documentation. You can easily create a custom tool based on the standard Javadoc Doclet in order to generate your own specific report, glossary, or diagram, as described in Chapter 6, “Automating Documentation.”

• Maven： Maven 和其他一些工具有一种内置的方式来生成一致的文档，通常作为网站，通过将许多工具报告和呈现的工件放在一起。例如，Maven 收集测试报告、静态分析工具报告、Javadoc 输出文件夹和任何 Markdown 文档，并将其全部组织到一个标准网站中。每个 Markdown 文档都可以在此过程中呈现。

• Maven: Maven and some other tools have a built-in way of producing consistent documentation, usually as a website, by putting together a number of tool reports and rendered artifacts. For example, Maven collects test reports, static analysis tools reports, Javadoc output folders, and any Markdown documents and organizes it all into a standard website. Every Markdown document can be rendered in the process.

• 精益酒吧：Leanpub，我用来写这本书的发布平台，是具有发布机制的单一来源的典型示例：每一章都写成一个单独的 Markdown 文件，图像保存在外部，代码可以放在自己的源文件中，并且甚至目录也在它自己的文件中。换句话说，内容以最方便使用的方式存储。每当我要求预览时，Leanpub 的出版工具链都会根据目录整理所有文件，并通过各种工具进行 Markdown 渲染、排版和代码突出显示，以生成多种格式的优质书籍：PDF、MOBI和 ePUB。这类似于出版界的小说手稿可以作为一本书、作为漫画出版，图 3.2）。您可以使用任何模板机制和一些自定义代码来遵循此基本模式。例如，您可以从资源文件中生成一个 PDF，其中列出了程序支持的每种货币。

• Leanpub: Leanpub, the publishing platform I used to write this book, is a canonical example of single sourcing with a publication mechanism: Every chapter is written as a separate Markdown file, images are kept outside, the code can be in its own source files, and even the table of contents is in its own file. In other words, the content is stored in the way it’s most convenient to work with. Whenever I ask for a preview, Leanpub’s publishing toolchain collates all files according to the table of contents and renders it through various tools for Markdown rendering, typesetting, and code highlighting in order to produce a good-quality book in multiple formats: PDF, MOBI, and ePUB. This is similar to how the manuscript of a novel in the publishing world can be published as a book, as a comics, and then later as a movie—all from the same initial manuscript (see Figure 3.2). You could follow this basic pattern with any templating mechanism and a bit of custom code. For example, you could produce a PDF out of the resource file that lists every currency supported by the program.

带有版本号的已发布快照

A Published Snapshot with a Version Number

从单一事实来源发布的任何文档都是快照：因此必须将其视为严格不可变的，并且永远不应进行编辑。为了避免有人编辑已发布文档的风险，您应该优先选择防止编辑的文档格式，或者至少使编辑变得困难的文档格式。例如，与 Microsoft Office 文档相比，人们更喜欢 PDF，因为 PDF 很容易更改。无论格式如何，请考虑使用锁定标志来防止编辑。这并不是要让黑客无法进行编辑；而是要让黑客无法进行编辑。相反，我们的想法是让编辑变得足够困难，以便最容易更改权威来源并再次发布。

Any document published from a single source of truth is a snapshot: It must therefore be considered as strictly immutable and should never be edited. To avoid the risk of having someone edit a published document, you should favor document formats that prevent editing—or at least that make editing difficult. For example, prefer PDF over Microsoft Office documents, which are very easy to change. Whatever the format, consider using the locking flags to prevent edits. It’s not about making it impossible for hackers to edit; rather, the idea is to make it just hard enough to make edits that it is easiest to change the authoritative source and have it published again.

任何发布的文档都必须清楚地标识其版本，并且还应包含指向可以找到最新版本的位置的链接。

Any published document must clearly identify its version and should also include a link to the location where the latest version can be found.

如果您生成大量要打印的纸质文档，您可以考虑在每个文档上贴上条形码，其中包含指向始终包含最新版本的文件夹的链接。这样，即使是印刷文档也可以轻松地将读者引导至最新版本。

If you produce a lot of paper documents to be printed, you may consider putting on each of them a barcode with the link to the folder that always contains the latest version. This way, even a printed document can easily direct readers to the latest version.

评论

Remarks

您应该仅手动编写无法从现有项目工件中提取的内容，并且应该将此类注释存储在具有自己的生命周期的文件中。理想情况下，该文件的更改频率比从其他地方提取的知识要少得多。另一方面，如果您需要发布的文档中缺少某些信息，您应该尽一切努力将其添加到与其最相关的工件中，也许使用注释、标签或命名约定，或者将其作为新的协作工件本身。

You should write by hand only what cannot be extracted from an already existing project artifact, and you should store such remarks in a file that has its own lifecycle. Ideally, this file will change much less frequently than the knowledge extracted from other places. On the other hand, if some information is missing from a document you need to publish, you should by all means try to add it to the artifact it is most related to, perhaps using annotations, tags, or naming convention, or make it a new collaborative artifact on its own.

运行一致性测试

Running Consistency Tests

正如第 2 章“行为驱动开发作为生活规范的示例”中提到的，使用 BDD，场景提供了行为的文档。每当场景和代码不一致时，您都会立即知道，因为测试自动化失败，就像 Roberval 天平一样（参见图 3.4）。

As mentioned in Chapter 2, “Behavior-Driven Development as an Example of Living Specifications,” with BDD, scenarios provide documentation of the behavior. Whenever a scenario and code disagree, you know it immediately because the test automation fails, much like a Roberval balance (see Figure 3.4).

这种机制的实现得益于以自然领域语言解析场景以驱动其实现代码的工具。该代码是通过专门为此目的编写的一小层粘合代码（通常称为“步骤定义”）驱动的。这些步骤是解析的场景和正在驱动的实际代码之间的适配器。

This mechanism is made possible thanks to tools that parse the scenario in natural domain language to drive their implementation code. The code is driven through a little layer of glue code that you write specifically for that purpose, usually called “step definitions.” These steps are adapters between the parsed scenario and the actual code being driven.

想象一下测试以下场景：

Imagine testing the following scenario:

• 指定方 BARNABA 被标记为破产

• Given party BARNABA is marked as bankrupt

• 交易 42 是针对 BARNABA，

• And trade 42 is against BARNABA,

• 当运行风险警报计算时，

• When the risk alerting calculation is run,

• 然后出现警报：触发针对破产方 BARNABA 的交易。

• Then an alert occurs: Trade against the bankrupt party BARNABA is triggered.

该工具解析这些文本行，并将“给定方 BARNABA 被标记为破产”这句话识别为具有步骤定义的句子：

The tool parses these lines of text and recognizes the sentence “Given party BARNABA is marked as bankrupt” as one it has a step definition for:

点击这里查看代码图片

Click here to view code image

1 Give("^一方(.*)被标记为破产$")
2公共无效partyMarkedAsBankrupt(string party){
3bankruptParties.put(party);
4 }

1 Given("^party (.*) is marked as bankrupt$")
2 public void partyMarkedAsBankrupt(string party){
3  bankruptParties.put(party);
4 }

该工具对每条线执行相同的操作。通常以When开头的句子触发实际计算，以then开头的句子提示工具检查断言：

The tool does the same for each line. Typically sentences starting with When trigger actual computation, and sentences starting with Then cue the tool to check assertions:

点击这里查看代码图片

Click here to view code image

1 然后(“^警报：(/*) 被触发$”)
2公共无效anAlertIsTriggered（字符串预期消息）{
3断言Equals（预期消息，实际消息）；
4 }

1 Then("^an alert: (/*) is triggered$")
2 public void anAlertIsTriggered(string expectedMessage){
3  assertEquals(expectedMessage, actualMessage);
4 }

/*为了使所有这些发挥作用，句子需要使用参数（句子中间的正则表达式 [ ]）实际驱动代码，并且断言必须尽可能精确地根据句子的期望进行检查。

For all of this to work, the sentences need to actually drive the code with parameters (the regular expression [/*] in the middle of the sentence), and the assertions must check against the expectations from the sentences as precisely as possible.

作为一个反例，在不从句子中提取参数的情况下对步骤进行编码是没有意义的，或者在进行一些更改后您将面临不一致的风险：

As a counter example, it would not make sense to code the step without extracting a parameter from the sentence, or you would run the risk of inconsistency after a few changes:

点击这里查看代码图片

Click here to view code image

1 然后（“^警告：针对破产方 BARNABA 的交易是
触发$")
3公共无效anAlertIsTriggered(){
4 assertEquals("与破产方进行交易
安然”，实际消息）；
5 }

1 Then("^an alert: Trade against the bankrupt party BARNABA is
triggered$" )
3 public void anAlertIsTriggered(){
4  assertEquals("Trade against the bankrupt party
ENRON",actualMessage);
5 }

不幸的是，即使硬编码消息不适合场景中的消息，场景仍然会通过，并且没有人会注意到。

The scenario would unfortunately still pass even when the hardcoded message does not fit the one in the scenario, and nobody would notice.

测试假设的调节

Reconciliation on the Test Assumptions

通常，您使用Give（或纯 xUnit 代码中的等效Arrange阶段）来创建模拟对象或将数据注入测试数据库。

Usually you use the Given (or the equivalent Arrange phase in plain xUnit code) to create mock objects or to inject data into the test database.

在测试遗留系统时，您通常必须处理几种类型的问题：

When testing legacy systems, you often have to deal with a couple types of problems:

• 模拟数据库太难了，因此您必须以端到端的方式进行测试。

• It’s too hard to mock the database, so you must test in an end-to-end fashion.

• 您无法仅为了测试而重新创建或填充数据库，因此您必须使用真正的共享数据库，如果其他人正在使用该数据库，该数据库可以随时更改。

• You can’t re-create or populate a database just for your tests, so you must work on a real shared database that can change anytime if someone else is working on it.

尽管存在这些问题，仍然可以使用与 xUnit 中的When语句或Arrange阶段完全相同的假设声明，但使用一个实现来检查假设是否仍然成立，而不是将值注入到模拟对象中：

Despite these problems, it’s still possible to use exactly the same declaration of an assumption as a When sentence or an Arrange phase in xUnit but with an implementation that checks that the assumption still holds true instead of injecting the value into a mock object:

点击这里查看代码图片

Click here to view code image

1 Give("^一方(.*)被标记为破产$")
2公共无效partyMarkedAsBankrupt(string party){
3assertTrue(bankruptParties.isBankruptParty(party)); // 调用
数据库
4 }

1 Given("^party (.*) is marked as bankrupt$")
2 public void partyMarkedAsBankrupt(string party){
3  assertTrue(bankruptParties.isBankruptParty(party)); // calls
the DB
4 }

这不是测试的断言；这只是场景（或测试）有机会通过的先决条件。如果这个假设已经失败，那么该场景“甚至不会失败”。我经常将这种“测试前的测试”称为金丝雀测试。此类测试可以告诉您即使在测试重点之外也存在问题，从而帮助您知道不必浪费时间在错误的地方进行调查。

This not an assertion of the test; it’s just a prerequisite for the scenario (or test) to even have a chance to pass. If this assumption already fails, then the scenario “does not even fail.” I often call this kind of “tests before the tests” a canary test. Such tests tell that something’s wrong even outside the test focus, helping you know that you don’t have to waste time investigating in the wrong place.

已发布的合同

Published Contracts

我第一次看到我的 Arolla 同事 Arnauld Loyer 使用的协调机制用于协调与第三方（例如调用您的服务的外部服务）的合同。如果您的服务公开带有参数 的资源CreditDefaultType（该参数有两个可能的值FAILURE_TO_PAY和 ）RESTRUCTURING，则发布后您将无法按照您的意愿重命名它们。因此，您可以使用具有故意冗余的测试来强制合同的这些元素不会更改。您可以根据需要进行重构和重命名，但每当您违反合同时，协调测试都会向您发出测试失败的警报。

A reconciliation mechanism that I first saw used by my Arolla colleague Arnauld Loyer is used to reconcile contracts against third parties such as external services that call your services. If your services exposes a resource with the parameter CreditDefaultType, which has the two possible values FAILURE_TO_PAY and RESTRUCTURING, you can’t rename them as you wish once published. You can therefore use tests with a deliberate redundancy to enforce that these elements of the contract don’t change. You can refactor and rename as you wish, but whenever you break the contract, the reconciliation tests will alert you with a test failure.

这是强制文档的一个示例。理想情况下，您应该以可读的形式将测试作为合同的参考文档；API 领域的一些工具可以帮助您做到这一点。这里你肯定不想通过自动重构来更新测试；相反，您希望它超出重构范围，以便它保持不变以代表外部消费者服务。

This is an example of enforced documentation. Ideally you would make the test the reference documentation for the contract, in a readable form; some tools in the API sphere enable you to do this. Here you definitely don’t want to update the test through automated refactoring; rather, you want it out of reach of the refactoring so that it stays unchanged to represent the external consumer services.

这种方法最简单的实现如下所示，假设 的内部表示CreditDefaultType是一个名为 的 Java 枚举CREDIT_DEFAULT_TYPE：

The most naive implementation for this approach would be something like that the following, assuming that the internal representation of the CreditDefaultType is a Java enum named CREDIT_DEFAULT_TYPE:

点击这里查看代码图片

Click here to view code image

1 @测试
2 公共无效forceContract_CreditDefaultType
3  最终String[] 合约 = {"FAILURE_TO_PAY",
“重组”}；
4
5   for (字符串类型：合约){
6assertEquals（类型，CREDIT_DEFAULT_TYPE.valueOf（类型）。
toString());
7}
8}

1 @Test
2 public void enforceContract_CreditDefaultType
3  final String[] contract = {"FAILURE_TO_PAY",
"RESTRUCTURING"};
4
5  for(String type : contract){
6  assertEquals(type, CREDIT_DEFAULT_TYPE.valueOf(type).
toString());
7  }
8 }

因为您希望确保遵守外部调用代码的约定，所以您再次将此约定定义为字符串数组，就好像它是从外部使用的一样。因为您想要检查合同是否正在使用传入和输出值进行磨练，所以您要确保合同字符串被识别为输入，并且valueOf()它是作为输出发送的字符串toString()。

Because you want to make sure that the contract for the external calling code is respected, you define this contract again as an array of strings, as if it’s being used from the outside. And because you want to check that the contract is being honed with incoming and outcoming values, you make sure the contractual string is recognized as an input with valueOf() and that it’s the one being sent as an output with toString().

通过这种方法，当最近加入团队的人决定重命名枚举常量时，测试立即无法表明不可能这样做，实际上就像防御性文档一样。这是对不当行为的防御，同时它为违规者提供了当场学习的机会：当测试失败时，他们了解到这个枚举常量是不应更改的合同的一部分。

With this approach, when someone who has recently joined the team decides to rename a constant of the enum, the test immediately fails to signal that it’s not possible to do that—in effect acting like defensive documentation. It’s a defense against misconduct, and at the same time it provides an opportunity for the violator to learn on the spot: When the test fails, they learn that this enum constant is part of a contract that should not be changed.

整合如何运作

How Consolidation Works

基本上，整合就像 SQL GROUP BY：您采用许多具有某些共同属性的事物，然后找到一种方法将所有这些多个事物转变为单个事物。实际上，它是通过扫描给定周长内的每个元素并增加结果来完成的，如图3.6所示。

Basically, consolidation is like a SQL GROUP BY: You take many things that have some properties in common, and you find a way to turn all those multiple things into a single thing. In practice, it’s done by scanning every element within a given perimeter, while growing the result, as shown in Figure 3.6.

例如，要在一个项目的范围内从各个元素重新构建类层次结构的完整图片，有必要扫描项目的每个类和每个接口。扫描过程保留了迄今为止正在构建的每个层次结构的不断增长的字典（例如，映射层次结构顶部 > 子类列表）。每次扫描遇到扩展另一个类或扩展接口的类时，都会将其添加到字典中。

For example, to reconstitute the full picture of a class hierarchy within the limits of one project from its individual elements, it’s necessary to scan every class and every interface of the project. The scanning process keeps a growing dictionary of every hierarchy under construction so far in the process (for example, with the mapping top of hierarchy > list of subclasses). Every time the scan encounters a class that extends another class or that extends an interface, it adds it to the dictionary.

扫描完成后，字典包含项目中所有类型层次结构的列表。当然，可以将流程简化为仅满足特定文档需求的感兴趣层次结构的子集，例如将扫描限制为属于已发布 API 的类和接口。

When the scan is done, the dictionary contains a list of all type hierarchies in the project. Of course, it’s possible to reduce the process to only a subset of the hierarchies of interest for a particular documentation need, such as restricting the scan to classes and interfaces that belong to a published API.

再举一个例子，您可以创建一个由较小组件组成的系统的黑盒生活图，每个组件都有自己的一组输入和输出，如图 3.7所示。

As another example, you can create a black-box living diagram of a system made of smaller components, each of which has its own set of inputs and outputs, as shown in Figure 3.7.

简单的合并可以收集每个组件的每个输入和输出的并集。更复杂的合并可以尝试删除内部相互匹配的每个输入和输出。您可以决定如何针对特定需求进行整合。

A simple consolidation can just collect the union of every input and output from each component. A more sophisticated consolidation can try to remove every input and output that match each other internally. It’s up to you to decide how you want consolidation to happen for a particular need.

合并实施注意事项

Consolidation Implementation Considerations

像往常一样，如果可能的话，您应该重用已有的可以进行所需整合的工具。例如，一些 Java 代码解析器可以提供类型层次结构。如果工具中没有您想要的内容，您可以添加它，例如通过在编程语言抽象语法树 (AST) ^{2上编写另一个访问者1}。一些更强大的工具甚至提供自己的语言来非常有效地查询代码库。如果您必须执行非常复杂的查询，您可能希望将 AST 加载到图形数据库中，但如果您这样做，恐怕您将成为文档工具的软件供应商。

As usual, if possible, you should reuse a tool you already have that can do a desired consolidation. Some parsers for Java code can provide type hierarchies, for example. If what you want is not already in the tool, you can add it, such as by writing another visitor¹ on the programming language Abstract Syntax Tree (AST)². Some more powerful tools even provide their own language to query the code base very efficiently. You might want to load the AST into a graph database if you have to do very complex queries, but if you do that, I’m afraid you’re becoming a software vendor of documentation tools.

1. Erich Gamma、John Vlissides、Ralph Johnson 和 Richard Helm 所著的《设计模式：可重用面向对象软件的元素》一书中的“访问者模式”艾迪生-韦斯利。

1.“The Visitor Pattern” from the book Design Patterns: Elements of Reusable Object-Oriented Software, by Erich Gamma, John Vlissides, Ralph Johnson, and Richard Helm. Addison-Wesley.

2.解析器用来表示和操作源代码结构的通用树结构。

2.A common tree structure used by parsers to represent and manipulate the structure of the source code.

如果出于性能问题而将派生知识保存在缓存中，请确保它不会成为事实来源，并且始终可以正确删除它，然后从所有事实来源从头开始重建。

If the derived knowledge is kept in a cache for performance issues, make sure it does not become a source of truth and that it can always be properly dropped and then rebuilt from scratch from all the sources of truth.

对于大多数系统，可以以批处理方式按顺序扫描所有部件。这通常是在构建过程中完成的，它会生成一个合并，可以在项目网站上发布或作为报告发布。

For most systems, it is possible to scan all parts in sequence in a batch-processing fashion. This is typically done during a build, and it produces a consolidation that is ready for publication on the project website or as a report.

对于诸如信息系统之类的大型系统，运行按顺序扫描所有部分的计算是不切实际的。在这种情况下，整合过程可以逐步完成。例如，每个部分的构建可能会通过将数据推送到共享位置（例如共享数据库）中某处的整体合并状态来贡献部分更新。这种合并状态是派生信息；它的可信度低于每个版本的信息。如果出现任何问题，您应该放弃它并让它从每个构建的贡献中再次增长。

For a large system such as an information system, it is not practical to run calculations that scan all parts in sequence. In such a case, the consolidation process may be done incrementally. For example, the build of each part might contribute a partial update by pushing data to an overall consolidation state somewhere in a shared place, such as a shared database. This consolidation state is derived information; it is less trusted than the information from each build. If anything goes wrong, you should drop it and let it grow again from the contributions of each build.

标准词汇的力量

The Power of a Standard Vocabulary

与世界上其他人使用相同的词语进行交谈是一个巨大的优势。它使您能够使用较短的句子进行交流。如果没有通用词汇，您可能会花费几句话来尝试描述文本编辑器的设计：

Talking using the same words as everybody else in the world is a fantastic advantage. It enables you to communicate using shorter sentences. Without a common vocabulary, you could spend several sentences trying to describe the design of a text editor:

但是，如果您熟悉设计模式等标准记录知识，则可以更简洁地表达您的观点：

However, if you’re familiar with standard documented knowledge like design patterns, you can get your point across more concisely:

每个成熟的行业都有自己丰富的术语，因为使用这些易于理解的术语是一种有效的沟通方式。汽车中的每个零件都有一个特定的名称，具体取决于其在车辆中的作用：轴不仅仅是轴，它是凸轮轴或曲轴。气缸中有一个活塞，还有推杆和正时链条。领域驱动设计提倡在领域中谨慎地发展这种无处不在的语言。

Each mature industry has its own rich jargon because using such understood jargon is an efficient way to communicate. Every part in a car has a specific name, depending on its role in the vehicle: A shaft is not just a shaft, it’s a camshaft or a crankshaft. There’s a piston in a cylinder, and there are pushrods and a timing chain. Domain-driven design advocates for carefully growing such ubiquitous language in the domain.

每当标准词汇量增长时，软件行业就会取得进步。例如，每当 Martin Fowler 为我们不假思索的模式创造另一个术语时，他就在帮助我们为我们的行业发展自己的无处不在的语言。

The software industry makes progress each time its standard vocabulary grows. For example, whenever Martin Fowler coins another term for a patterns that we do without thinking about it, he is helping grow our own ubiquitous language for our industry.

通用语言对文档非常有帮助。如果您知道自己在做什么并且知道它在行业中的名称，那么您只需插入对行业标准的引用，就可以以较低的成本获得广泛的文档。

Ubiquitous language is extremely helpful in documentation. If you know what you’re doing and you know what it’s called in the industry, you can just insert a reference to the industry standard, and you have achieved extensive documentation at low cost.

模式和模式语言对于将现成的知识打包到可重用的文档中特别有效。模式实际上是罐装文档。他们创建了一个标准词汇表，您可以使用和参考以获得完整的参考。

Patterns and pattern languages are particularly effective at packing ready-made knowledge into a reusable documentation. Patterns really are canned documentation. They create a standard vocabulary you can use and refer to for complete reference.

了解标准词汇还可以打开获得更多知识的大门：您可以找到有关您感兴趣的主题的书籍并购买培训。您还可以找到具有这些知识的人员并雇用他们。

Knowing the standard vocabulary also opens the door to even more knowledge: You can find books and buy training on the topic you’re interested in. You can also pinpoint people with this knowledge and hire them.

了解标准词汇并不意味着找到解决方案。即使您有一个完美的解决方案，也值得了解一下它在行业中的名称。标准词汇表使您能够参考其他人的工作，他们以精心编写、经过同行评审和经过时间考验的方式描述了解决方案。

Knowing the standard vocabulary is not so much about finding a solution. Even when you have a perfect solution, it’s worth finding out what it’s called in the industry. A standard vocabulary enables you to refer to the work of other people who describe a solution in a well-written, peer-reviewed, and time-tested fashion.

链接到标准知识

Linking to Standard Knowledge

通用知识已经记录在行业文献、书籍和在线中。使用时，请通过互联网链接或参考书目链接到权威来源。如果某件事曾经写得很好，你应该参考它，而不是重新做一次较差的记录工作。

Generic knowledge is already documented in the industry literature, in books, and online. When you use it, link to the authoritative source via an Internet link or a bibliographic reference. If something has been written well once, you should refer to it rather than redo a poorer job of documenting it again.

当然，一个大问题可能是确定某条知识的标准名称。Google 等搜索引擎以及 C2 和 Stack Overflow 等社区网站是您的朋友。您可能必须猜测其他人如何谈论某个话题。然后，您可以快速扫描第一个搜索引擎结果，以确定更准确的词汇表，可以帮助您进行更窄的查询。通过这种探索，您将很快学到很多东西，并了解该主题的多少内容已经被编码以及使用了哪些术语。

Of course, one big problem can be identifying the standard name for a piece of knowledge. Search engines like Google and community websites like C2 and Stack Overflow are your friends. You might have to guess how others talk about a topic. Then you can quickly scan the first search engine results to determine a more accurate vocabulary that can help you make narrower queries. Through this exploration, you’ll quickly learn a lot and get to see how much of the topic is already codified and using what terminology.

不要犹豫，在您的团队或论坛上四处询问建议。其他人可能有经验和资历，并且有更多的时间来索引他们多年来遇到的标准知识的指针，即使是表面的。

Don’t hesitate to ask around—in your team or on a forum—for suggestions. Other people may have experience and seniority and more time to index pointers to standard knowledge they’ve encountered, even superficially, over the years.

从给定的术语，您还可以浏览维基百科以及文章末尾的所有各种链接。还要留意底部的“相关”链接，直到您认识到自己的情况。维基百科是一个很棒的工具，可以将标准词汇映射到您自己的心理世界。

From a given term, you can also browse Wikipedia and all the various links at the ends of the articles. Keep an eye on the bottom “related” links as well, until you recognize your situation. Wikipedia is a fantastic tool for mapping a standard vocabulary to your own mental universe.

不仅仅是词汇

More Than Just Vocabulary

拥有共享的标准词汇是有效进行口头和书面沟通的关键优势。也就是说，即使是标准描述也可能涉及您未考虑过的改进和替代方案。这些信息也很有用。现成的文档实际上是可重用的思维，这是有很大帮助的。这有点像作者（通常是经验丰富的实践者）靠近您，以便您可以一起思考。

Having a shared standard vocabulary is a key advantage in communicating effectively, both verbally and in writing. That said, even a standard description may involve refinements and alternatives you haven’t considered. That information is useful, too. Ready-made documentation is in fact reusable thinking, which is a great help. It’s a bit like having the author, usually a seasoned practitioner, close to you so you can think together.

如果我说“我在遗留子系统之上创建一个适配器”，这句话用几句话就意味着很多事情，因为适配器模式的想法不仅仅是一个名称。例如，此模式的一个重要结果是适配器（我们示例中的遗留子系统）不应该知道适配器；只有适配器应该知道遗留子系统。

If I say that “I create an adapter on top of the legacy subsystem,” this sentence implies a lot of things in a few words, because there’s more than a name in the idea of the adapter pattern. For example, an important consequence in this pattern is that the adaptee—the legacy subsystem in our example—should not know about the adapter; only the adapter should know about the legacy subsystem.

当我说一个包代表表示层，而另一个包代表领域层时，我还暗示只有前者可以依赖后者，而不能反过来。

When I say that a package represents the presentation layer, whereas this other package represents the domain layer, I also imply that only the former can depend on the latter—and never the other way around.

数学中的常态是重用定理和共享文献中的抽象结构，以进一步发展，而无需重新发明和一次又一次地证明相同的结果。标准词汇也是如此。

It’s the norm in mathematics to reuse theorems and shared abstract structures from the literature to go further without reinventing and having to prove the same results again and again. The same goes for a standard vocabulary.

在对话中使用现成的知识来加速知识转移

Using Ready-Made Knowledge in Conversation to Speed Up Knowledge Transfer

以下是我与我的朋友 Jean-Baptiste Dusseaut（简称“JB”，Twitter 上的@BodySplash）的一段简短对话，旨在说明共同的文化和词汇如何帮助有效地共享知识（见图 3.8 ）。

Here’s a little conversation I had with my friend Jean-Baptiste Dusseaut (“JB” for short, @BodySplash on Twitter) to illustrate how a common culture and vocabulary can help with sharing knowledge efficiently (see Figure 3.8).

注释不仅仅是标签

Annotations as More Than Tags

Java 中的注释和 .Net 中的属性是其编程语言的真正公民。它们有一个名称和一个模块名称（包或命名空间）。它们还保存参数，并且本身可以由其他注释进行注释。而且因为它们是类，所以它们还受益于 Javadoc 等文档生成器使用的结构化注释语法。所有这一切意味着您可以通过简单的注释传达大量知识。

Annotations in Java and attributes in .Net are genuine citizens of their programming language. They have a name and a module name (package or namespace). They also hold parameters and can themselves be annotated by other annotations. And because they are classes, they also benefit from the structured comments syntax used by documentation generators like Javadoc. All this means you can convey a lot of knowledge through simple annotations.

让我们看一个技术示例。注释使用元注释来描述它们的应用位置。例如，这里的注释Adapter可以应用于类型和包：

Let’s look at a technical example. Annotations use meta-annotations to describe where they can be applied. For example, here the annotation Adapter can be applied to types and packages:

点击这里查看代码图片

Click here to view code image

1 @Target({ ElementType.TYPE, ElementType.PACKAGE })
2 公共@interface适配器{
3 }

1  @Target({ ElementType.TYPE, ElementType.PACKAGE })
2  public @interface Adapter {
3  }

以下示例涉及带有参数的注释。如果要注释构建器模式的实例，则可以将构建器生成的类型描述为注释的参数：

The following example involves annotations with parameters. If you were to annotate an instance of a builder pattern, you could describe the type that the builder produces as a parameter of the annotation:

点击这里查看代码图片

Click here to view code image

1 公共@interface Builder {
2 Class[] products() 默认 {};
3 }
4
5 @Builder(产品 = {Supa.class, Dupa.class})
6 公共类 SupaDupaBuilder {
7 //...
8}

1  public @interface Builder {
2  Class[] products() default {};
3  }
4
5  @Builder(products = {Supa.class, Dupa.class})
6  public class SupaDupaBuilder {
7  //...
8  }

通常，声明的返回类型和实现的接口已经可以讲述很多类似的信息，但它们错过了附加注释传达的精确语义。事实上，更精确的注释为更多自动化打开了大门，因为它们为工具提供了一种用更高级别的语义解释源代码的方法。

Often the declared return types and implemented interfaces can already tell a lot of similar information, but they miss the precise semantics that additional annotations convey. In fact, more precise annotations open the door to more automation because they give tools a way to interpret the source code with higher-level semantics.

正如语义网旨在将非结构化数据转换为数据网络一样，带有澄清源代码语义的注释的代码库也成为机器可以解释的数据网络。

Just as the Semantic Web aims to transform unstructured data into a web of data, a code base with annotations that clarify the semantics of the source code becomes a web of data that machines can interpret.

描述决策背后的理由

Describing the Rationale Behind Decisions

值得为子孙后代记录的最重要的信息之一是每个决定背后的理由。几年后看起来可能是一个愚蠢的选择，但当它做出决定时并不那么愚蠢。最重要的是，当理由是指某个时间点的上下文，而现在上下文不同时，您现在可以更好地重新考虑该决定。

One of the most important pieces of information worth recording for future generations is the rationale behind each decision. What may seem like a stupid choice years later was not so stupid when it was decided. Most importantly, when the rationale is referring to a context at some point in time, and now the context is different, you are in a better position to reconsider the decision now.

例如，假设很久以前就选择了一个昂贵的数据库，因为它是少数能够在内存中完全缓存数据的数据库之一。现在阅读此基本原理，您可能会考虑使用 NoSQL 数据存储来实现此目的。再举一个例子，假设应用程序的各个层都通过 XML 相互通信，这会让您的生活变得很麻烦并导致性能问题。这一决定的基本原理是，该架构旨在物理分布在各层之间，以便进行扩展。然而，多年后，很明显这永远不会发生，所以您现在知道您可以消除所有额外的复杂性。如果没有明确的理由，你总是会怀疑自己是否错过了什么，并且不敢重新考虑整个事情。

For example, say that an expensive database was chosen long ago because it was one of the few to be able to fully cache data in memory. Reading this rationale now, you may consider instead using NoSQL datastores for that purpose. As another example, say that an application has layers talking to each other through XML everywhere, which makes your life cumbersome and causes performances issues. The rationale for this decision explains that this architecture was meant to be distributed physically between layers in order to scale. However, after many years, it has become clear that this will never happen, so you know now that you could remove all the extra complexity. Without a clear rationale, you would always wonder if you had missed something, and you would not dare reconsidering the whole thing.

嵌入式学习

Embedded Learning

将更多知识放入代码中可以帮助维护人员在工作时学习。至少，注释本身应该被记录下来。如果您有一个名为 的注释Adapter，它的注释应该解释它Adapter是什么。我最喜欢的方法是链接到清晰的在线定义，例如相应的维基百科页面，以及评论本身中的简短文本描述：

Putting more knowledge into code helps its maintainers learn while working on it. At a minimum, annotations should themselves be documented. If you have an annotation named Adapter, its comments should explain what Adapter is. My favorite way to do this is to link to a clear online definition, such as the corresponding Wikipedia page, along with a brief text description within the comment itself:

点击这里查看代码图片

Click here to view code image

1   /** 
2   * 适配器模式是一种软件设计模式，
允许另一个类使用现有类的
3   * 接口
界面。
4   * 
5   * 适配器包含它包装的类的实例，并且
6   * 将调用委托给包装对象的实例。
7   * 
8   * 参考：参见 <a href="http://en.wikipedia.org/wiki/\
9 * Adapter_pattern"> Adapter_pattern </a>
10 */ 
11  公共@接口适配器{
12}

1  /**
2  * The adapter pattern is a software design pattern that
allows the
3  * interface of an existing class to be used from another
interface.
4  *
5  * The adapter contains an instance of the class it wraps, and
6  * delegates calls to the instance of the wrapped object.
7  *
8  * Reference: See <a href="http://en.wikipedia.org/wiki/\
9  * Adapter_pattern">Adapter_pattern</a>
10 */
11  public @interface Adapter {
12  }

这比看起来更重要。从现在开始，带有此注释的每个类都只需一个工具提示即可获得其设计角色的完整文档。

This is more important than it might seem. From now on, every class with this annotation is only a tooltip away from complete documentation of its design role.

Adapter考虑项目中随机类的示例，在本例中位于 RabbitMQ 中间件之上：

Consider the example of a random Adapter class in a project, in this case on top of the RabbitMQ middleware:

点击这里查看代码图片

Click here to view code image

1 @适配器
2 公共类RabbitMQAdapter {
3   //... 
4 }

1 @Adapter
2 public class RabbitMQAdapter {
3  //...
4 }

当在任何 IDE 中打开此类时，当鼠标悬停在其上时，工具提示会显示其文档，如图4.2所示。

When this class is opened in any IDE, when the mouse hovers over it, the tooltip displays its documentation, as shown in Figure 4.2.

工具提示描述提供了简短的解释，但对于已经了解该信息但只需要复习一下的开发人员特别有用。如果需要比工具提示提供的更多信息，可以单击链接以重定向到更多信息。他们可能会在此过程中提出问题，但至少有一个简单的学习切入点。在本例中，注释描述了该类Adapter是适配器模式的实例，并且它们充当了解有关适配器模式的更多信息的门户。

The tooltip description provides a brief explanation but is especially useful for developers who already know the information but just need a refresher. Those who need more information than the tooltip provides can click the link to be redirected to more information. They will probably ask questions in the process, but at least there’s an easy entry point to the learning. In this case, the annotations describe that the Adapter class is an instance of the adapter pattern, and they act as a gateway to learning more about the adapter pattern.

因此：将更多的知识放入代码中不仅仅是为了文档；它还可以帮助有意识地提高从事该工作的团队的技能。在决定增强代码策略时请考虑这个机会。扩充代码时，请考虑您的同事发现它时会如何反应。

Therefore: Putting more knowledge into the code is not just for documentation; it can also help deliberately increase the skills of the teams working on it. Consider this opportunity when deciding on your augmented code strategy. When augmenting code, think about how your colleagues will react when they discover it.

注释还可以链接到最能解释该主题的一本书或几本书。或者它可以链接到公司的电子学习计划。

An annotation could also link to the book or books that best explain the topic. Or it could link to a company e-learning program.

作为在评论中包含链接的替代方案，同一本书中的每个注释都可以有一个代表该书的元标签。在下面的示例中，Adapter和Decorator注释都代表来自《四人帮》一书《设计模式》GoF的设计模式，有关该书的信息可以包含在专门与该书相关的元注释中：

As an alternative to including links in comments, every annotation from the same book could have a meta-tag representing the book. In the following example, both Adapter and Decorator annotations represent design patterns from the Gang of Four book Design Patterns, and information about the book can be included in a meta-annotation GoF specifically about the book:

点击这里查看代码图片

Click here to view code image

1   /** 
2   * 书籍： <a href="http://books.google.fr/books/about/Design_
3 Patterns.html?id=6oHu\KQe3TjQC">Google 图书</a>
4   */
5 @Target(ElementType.ANNOTATION_TYPE)
6 公共@interface GoF {
7}
8
9 @GoF
10 公共@interface适配器{
11}
12
13 @GoF
14 公共@interface装饰器{
15}

1  /**
2  * Book: <a href="http://books.google.fr/books/about/Design_
3  Patterns.html?id=6oHu\KQe3TjQC">Google Book</a>
4  */
5  @Target(ElementType.ANNOTATION_TYPE)
6  public @interface GoF {
7  }
8
9  @GoF
10 public @interface Adapter {
11 }
12
13 @GoF
14 public @interface Decorator {
15 }

这只是一个示例，当然您不仅限于记录设计模式！请随意根据这些想法详细阐述您自己的组织知识的计划。

This is only an example, and of course you are not limited to documenting design patterns! Feel free to elaborate your own scheme for organizing your knowledge based on these ideas.

1 /** @适配器 */

1 /** @Adapter */

1 公共类 MyDto 实现可序列化 {
2 ...
3 }

1  public class MyDto implements Serializable {
2    ...
3  }

1 @捂脸
2 if(找到== true){...}

1  @Facepalm
2  if(found == true){...}

1 @LOL @Facepalm @WTF(“只需使用 Collections.reverse()”)
2 <T> void invertOrdering(List<T> 列表) {...

1  @LOL @Facepalm @WTF("just use Collections.reverse()")
2  <T> void invertOrdering(List<T> list) {...

1 @Hack 公共字符串
2 unescapePseudoEscapedCommasAndSemicolons(String url) {

1  @Hack public String
2  unescapePseudoEscapedCommasAndSemicolons(String url) {

1 @BossMadeMeDoIt
2 字符串 extractSQLRequestFromFormParameter(字符串
参数）{...}

1 @BossMadeMeDoIt
2 String extractSQLRequestFromFormParameter(String
params){...}

1 @Magic public static int negate(int n) {
2 返回 new Byte((byte) 0xFF).hashCode()
3 / (int) (短) '\uFFFF' * ~0
4 * 字符.数字('0', 0)
5  * n * (整数.MAX_VALUE * 2 + 1) / (字节.MIN_VALUE >> 7)
6 1 * (~1 | 1);
7}

1 @Magic public static int negate(int n) {
2  return new Byte((byte) 0xFF).hashCode()
3  / (int) (short) '\uFFFF' * ~0
4  * Character.digit ('0', 0)
5  * n * (Integer.MAX_VALUE * 2 + 1) / (Byte.MIN_VALUE >> 7)
6  1 * (~1 | 1);
7 }

1 @Metaphor 公共接口 Life 扩展 Box { }

1 @Metaphor public interface Life extends Box { }

1 @Oxymoron 公共接口 DisassemblerFactory {
反汇编器
2 创建反汇编器(); }

1  @Oxymoron public interface DisassemblerFactory {
Disassembler
2  createDisassembler(); }

带有约定的遗留代码中的活文档

Living Documentation in Legacy Code with Conventions

每当您拥有遵循约定的现有代码库时，您就有机会通过利用所有现有约定来走活文档路线，甚至无需接触源代码来添加任何内容。（这对于注释文档来说是不可能的。）

Whenever you have an existing code base that follows conventions, you have an opportunity to go the living documentation route by exploiting all the existing conventions, without even having to touch the source code to add anything. (This is not possible with documentation by annotation.)

例如，假设现有应用程序遵循分层设计。如果幸运的话，它的包名称通过命名约定直接代表各层：

For example, say that an existing application follows a layered design. If you’re lucky, its package names represent the layers directly through naming conventions:

点击这里查看代码图片

Click here to view code image

1 /记录存储目录/gui
2 /记录存储目录/businesslogic
3 /记录存储目录/dataaccesslayer
4 /记录存储目录/数据库模式

1  /record-store-catalog/gui
2  /record-store-catalog/businesslogic
3  /record-store-catalog/dataaccesslayer
4  /record-store-catalog/db-schema

您的文档已经存在于 Java 包的命名中或者 C# 中的命名空间或子项目中。

Your documentation is already there in the naming of the Java packages or in namespaces or subprojects in C#.

记录约定

Documenting the Conventions

如果团队中的每个人都熟悉所使用的约定，那么您不需要任何进一步的文档。其他公司发布的约定称为现成文档，您可以采用此类约定，然后只需在 README 文件中创建对约定集的外部文档的引用即可。但在实践中，我建议始终在自述文件中记录约定。这是在真实代码库中记录约定的示例：

If everyone on a team is familiar with the conventions used, then you don’t need any further documentation. Conventions published by another company are called ready-made documentation, and you can adopt such conventions and then just create a reference to the external documentation of the sets of conventions in the README file. In practice, though, I recommend always documenting the conventions in the README file. Here’s an example of documenting conventions in a real code base:

点击这里查看代码图片

Click here to view code image

1 自述文件.txt
2
3 该应用程序遵循分层架构。
4 每一层都有自己的包，命名如下
5个约定：
6
7 /图形用户界面/*
8 /业务逻辑/*
9 /数据访问层/*
10 /db-模式/*
11
12 GUI层包含有关图形用户的所有代码
13个接口。
14 所有负责显示和数据输入的代码都必须存在。
15
16 业务逻辑层包含所有特定领域的
17 逻辑和行为。这就是领域模型所在的地方。
18 业务逻辑应该只存在于此处，而不应存在于其他地方。
19
20 数据访问层包含所有的DAO（Data Access
21个对象）负责与数据库交互。
22 存储技术的任何变化只会影响
23 这一层，没有其他层（至少理论上是这样：）
24
25 DB Schema 包含所有要设置、删除的 SQL 脚本
26或更新数据库。
27
28 重要规则：每一层只能依赖于该层
29 以下。任何层都不能依赖于上面的一个或多个层，
30 这是禁止的！

1 README.txt
2
3 This application follows a Layered Architecture.
4 Each layer has its own package, with the following naming
5 conventions:
6
7 /gui/*
8 /businesslogic/*
9 /dataaccesslayer/*
10 /db-schema/*
11
12 The GUI layer contains all the code about the graphical user
13 interface.
14 All code responsible for display & data entry must be there.
15
16 The business logic layer contains all the domain-specific
17 logic and behavior. This is where the domain model is.
18 Business logic should only be there and nowhere else.
19
20 The data access layer contains all the DAO (Data Access
21 Objects) responsible to interact with the database.
22 Any change of storage technology should only impact
23 this layer and no other layer (in theory at least :)
24
25 The DB Schema contains all the SQL scripts to setup, delete
26 or update the database.
27
28 Important Rule: Each layer can only depend on the layers
29 below. No layer can depend on the layer or layers above,
30 this is forbidden!

有些约定是有代价的，特别是当它们给命名带来干扰时。例如，在标识符上添加前缀或后缀（例如，VATCalculation-Service, DispatchingManager, DispatchingDTO）是一种标准做法，但这不是干净的代码，并且代码中的名称不再属于业务领域语言！

Some conventions carry a cost, especially when they add noise to the naming. For example, putting prefixes or suffixes on identifiers (for example, VATCalculation-Service, DispatchingManager, DispatchingDTO) is a standard practice, but it’s not clean code, and the names in your code do not belong to the business domain language anymore!

当包中的每个接口都是服务时，添加Service前缀不会添加任何信息，只会添加噪音。如果包中的每个类都是冗余信息，则/dto/可能不需要后缀。DTO

When every interface in a package is a service, adding the Service prefix adds no information, just noise. Every class in a /dto/ package might not need the DTO suffix if it would be redundant information.

一贯遵守惯例

Consistently Adhering to Conventions

只有当每个参与人员都有足够的纪律来始终遵守约定时，按惯例编写的文档才有效。编译器不关心您的约定，并且对强制执行它们没有太大帮助。

Documentation by convention works only to the extent that everyone involved has enough discipline to adhere to the conventions consistently. The compiler does not care about your conventions and won’t help much in enforcing them.

一处拼写错误，你就已经不遵守惯例了！当然，您可以调整编译器或 IDE 解析器，也可以使用静态分析工具来检测某些违反约定的情况。有时需要做很多工作，但有时却出奇的简单，所以你可以尝试一下。

One typo, and you’re already not following the convention! You can, of course, tweak the compiler or your IDE parser, or you can use static analysis tools to detect some violations of conventions. Sometimes it’s a lot of work, but other times it’s surprisingly easy, so you may give it a try.

依靠约定的文档来帮助生成活文档（例如动态图表）会鼓励并奖励遵循约定：如果您违反约定，那么您的活文档将会失败，这很好。

Relying on documentation by convention to help produce living documents such as living diagrams encourages and rewards following the conventions: If you break the convention, then your living documents will fail, which is nice.

约定的局限性

The Limitations of Conventions

约定对于对代码段进行分类非常有效，但是当您尝试用附加知识（例如基本原理、替代方案等）来丰富它们时，它们很快就会显示出其局限性。相比之下，注释可能能够更好地包含此类附加知识。

Conventions work well for categorizing sections of code, but they quickly show their limits when you try to enrich them with additional knowledge such as rationales, alternatives, and so on. In contrast, annotations may be better able to include such additional knowledge.

约定通常只不过是供人类使用的自由文本。但是，您仍然可以获得一些针对您的约定的工具支持：

Conventions are often little more than free text meant for humans. However, you may still get some tool support for your conventions:

• 您可以使用每个约定的模板来配置 IDE。例如，您可以输入几个字符并让模板正确打印全名以遵守约定；对于具有更复杂约定的提交注释，模板可能会打印一个您可以填写的占位符。

• You can configure your IDE with templates for each convention. For example, you might be able to type a few characters and have the template print the full name properly to adhere to the convention; for a commit comment with a more complicated convention, the template might print a placeholder that you can just fill in.

• 您可以让您的活文档生成器解释约定来执行其工作。

• You can have your living document generators interpret the conventions to perform their work.

• 您可以根据命名约定（例如，使用 JDepend、ArchUnit 或您自己构建在任何代码解析器之上的工具）强制执行规则，例如层之间的依赖关系。

• You can enforce rules such as dependencies between layers based on the naming conventions (for example, using JDepend, ArchUnit, or your own tool built on top of any code parser).

与注释相比，约定还具有不打乱旧习惯的优点。如果您的团队和经理非常保守，您可能更喜欢按约定路线查看文档，而不是按注释路线查看文档。您可能会猜到我更喜欢通过注释来记录文档。

Compared to annotations, conventions also have the advantage of not disrupting old habits. If your team and managers are very conservative, you may prefer going the documentation by convention route rather than the documentation by annotation route. You can probably guess that I prefer documentation by annotation.

边车文件

Sidecar Files

当无法将注释放入代码中时，您可以将它们放入代码旁边的文件中。Sidecar 文件（也称为伙伴文件、伴随文件或连接文件）是存储源文件格式无法支持的元数据的文件。对于每个源文件，通常有一个关联的 sidecar 文件，其名称相同但文件扩展名不同。

When putting annotations within code is not possible, you can put them into a file next to the code. Sidecar files—also known as buddy files, companion files, or connected files—are files that store metadata that cannot be supported by the source file format. For each source file, there is typically one associated sidecar file with the same name but a different file extension.

例如，某些 Web 浏览器将网页保存为一对文件：一个 HTML 文件和一个同名但带有 _folder 前缀的 sidecar 文件夹。作为另一个示例，数码相机可能能够在拍照时记录一段音频，并且相关联的音频可以存储为与 .jpg 文件同名的 sidecar 文件，但扩展名为 .wav。

For example, some web browsers save a web page as a pair of files: an HTML file and a sidecar folder of the same name but with a _folder prefix. As another example, a digital camera might have the capability to record a piece of audio while taking a picture, and the associated audio may be stored as a sidecar file with the same name as the .jpg file, but with a .wav extension.

Sidecar 文件是一种外部注释。它们可用于添加任何类型的信息，例如分类标签或自由文本注释，而无需触及文件系统上的原始源文件。

Sidecar files are a type of external annotations. They can be used to add any kind of information, such as a classification tag or a free text comment, without having to touch the original source file on the file system.

使用 sidecar 文件的主要问题是，当文件管理器不知道源文件与其 sidecar 文件之间的关系时，它无法阻止用户仅重命名或移动其中一个文件而不移动另一个文件，并且该关系是破碎的。因此，我不建议使用 sidecar 文件，除非你别无选择。

The main problem with using sidecar files is that when the file manager is not aware of the relationship between the source file and its sidecar file, it cannot prevent the user from renaming or moving only one of the files without the other, and the relationship is broken. For this reason, I don’t recommend using sidecar files unless you have no other choice.

元数据数据库

Metadata Databases

当无法在代码中添加注释时，您可以将它们保存在外部数据库中。元数据数据库是存储引用其他源文件或组件的元数据的数据库。一个众所周知的例子是 iTunes 数据库，其中包含许多与每首歌曲相关的元数据（例如，播放列表、最近的收听历史记录），但这些元数据不适合歌曲的音频文件。元数据可能不适合该文件，因为该文件格式没有地方存储元数据，或者根本不应该更改该文件。

When putting annotations within code is not possible, you can keep them in an outside database. A metadata database is a database that stores metadata referencing other source files or components. A well-known example is the iTunes database, which contains a lot of metadata associated with each song (for example, playlists, recent listening history) that doesn’t fit within the song’s audio file. The metadata might not fit within the file because the file format does not have a place to store the metadata or because it would not be a good idea to change the file at all.

元数据也可能引用文件，但实际上并不是文件固有的，因此它应该存储在其他地方。例如，照片不应存储有关其属于相册的一部分的信息；最好把专辑存放在某个地方别的。以类似的方式，照片缩略图的 URL 是仅照片应用程序感兴趣的元数据，通过在照片文件自己的结构中包含此类元数据来破坏照片文件将是侵入性的（假设它甚至是可能的）。

Metadata may also reference a file but not really be intrinsic to it, and hence it should be stored somewhere else. For example, a photo should not store information about its being part of an album; it would be better to store the album somewhere else. In a similar fashion, the URL of the thumbnail of a photo is metadata that is of interest only for the photo application, and it would be intrusive to corrupt the photo file by including that kind of metadata in its own structure (assuming it were even possible).

使用元数据数据库进行注释的主要问题，就像使用 sidecar 文件的主要问题一样，如果元数据数据库和相应文件之一在未经授权的情况下被重命名、移动或删除，则很容易导致元数据数据库和相应文件不同步。数据库正在更新。

The main problem with using metadata databases for annotations, just like the main problem with using sidecar files, is that it’s easy for the metadata database and the corresponding files to get out of sync if one of these files is renamed, moved, or deleted without the database being updated.

当根本无法触及文件并且元数据必须存储在其他地方时，元数据数据库应该是最后的选择。然而，当元数据的管理由不同的人而不是管理文件本身的人同时对所有文件进行批量管理时，这也是一种方便的方法。例如，如果摄影师管理数百张照片，但元数据数据库是由图书馆员管理的普通电子表格，那么图书馆员可以轻松快速地将所有元数据添加到列中，这要归功于复制/粘贴，现代电子表格应用程序的插值和计算能力。摄影师不必参与，也不存在错误损坏照片文件的风险。

A metadata database should be the last-resort choice when it’s not possible to touch the files at all and metadata has to be stored elsewhere. However, it is also a convenient approach when the management of the metadata is done in bulk across all files at the same time, by different people than the people managing the files themselves. For example, if hundreds of photos are managed by a photographer, but the metadata database is a plain spreadsheet managed by a librarian, then it is easy  for the librarian to quickly add all the metadata in a column, thanks to the copy/paste, interpolation, and calculation abilities of a modern spreadsheet application. The photographer does not have to be involved, and there is no risk of corrupting the photo file by mistake.

元数据数据库的常见示例是发现注册表中嵌入的各种键/值存储；部署、配置和供应工具；服务目录；为注册表添加书签；等等。每当您可以引用某些内容并添加标签时，您就拥有了一个事实上的元数据数据库！

Common examples of metadata databases are the various key/value stores embedded in discovery registries; deployment, configuration, and provisioning tools; service catalogs; bookmarking registries; and so on. Whenever you can reference something and add tags, you have a de facto metadata database!

刻板属性

Stereotypical Properties

当我们设计代码时，我们会考虑工作行为以及属性（无论是否理想）。以下是一些理想属性的示例：

When we design code, we think in terms of working behavior and also in terms of properties, desirable or not. Here are some examples of desirable properties:

• NotNull:对于不能为空的参数。当您几乎总是使用它时，生活会变得更加轻松！

• NotNull: For a parameter that cannot be null. Life is so much easier when you use it almost always!

• Positive:对于必须为正的参数。

• Positive: For a parameter that has to be positive.

• Immutable:对于保持不变的类。

• Immutable: For a class that remains unchanged.

• Identity by value:其中平等被定义为数据的平等。

• Identity by value: Where equality is defined as the equality of data.

• Pure:对于一个函数或一个类的每个函数以避免副作用。

• Pure: For a function or for every function of a class to avoid side effects.

• Idempotent:对于多次调用时具有相同效果的函数（这在分布式系统中非常重要）。

• Idempotent: For a function that has the same effect when called more than once (which is very important in distributed systems).

• Associative:对于诸如 (a + b) + c = a + (b + c) 之类的函数，在执行 map-reduce 类操作时。

• Associative: For a function such as (a + b) + c = a + (b + c), when doing map-reduce kinds of things.

当你使用这些属性时，你需要在代码中明确你的用法。只要有可能，您就可以使用类型系统来完成此操作。例如，如果它内置于语言中或由标准库提供，则Option可以表达没有结果的可能性。Optional使用 Scala案例类本身就是(Immutable, Identity by value)的简写。如果无法做到这一点，您可以使用注释或自定义注释以及自动化测试和基于属性的测试来表达属性。

When you use these properties, you need to make your usage clear in the code. You can do this with the type system whenever possible. For example, it is possible to express the possibility of having no result with Option or Optional if it is built in to the language or provided by a standard library. Using a Scala case class is in itself a shorthand for (Immutable, Identity by value). When this is not possible, you can express the properties with comments or with custom annotations, along with automated tests and property-based testing.

刻板印象和战术模式

Stereotypes and Tactical Patterns

在 Java 或 C# 等语言中，一切都是类，但并非每个类都属于同一类型或具有相同的用途。请注意，在函数式编程语言中，一切都是函数，但并非每个函数都有相同的用途。领域驱动设计提出了一些基本的类类别，例如值对象、实体、领域服务和领域事件。它还建议借鉴其他模式，例如使用设计模式（例如，策略和复合模式）。关键是一些（但不是全部）设计模式也是领域模式。

In a language like Java or C#, everything is a class, but not every class is of the same kind or has the same purpose. Note that in functional programming languages, everything is a function, but not every function has the same purpose either. Domain-driven design proposes some fundamental categories of classes, such as value object, entity, domain service, and domain event. It also suggests borrowing from other patterns, such as using design patterns (for example, strategy and composite patterns). The point is that some (but not all) design patterns are also domain patterns.

有趣的是，这些类别的类提供了表达大量信息的压缩方式。例如，当我说类FueldCardTransaction是一个值对象时，我的意思是它的身份仅由它的值定义，它是不可变的，它应该没有任何副作用，并且它应该是可转移的。因此，很自然地明确声明这些模式作为编写文档的简单方法。

It is interesting that these categories of classes offer compressed ways to express a lot of information. For example, when I say that the class FueldCardTransaction is a value object, I mean that its identity is only defined by its values, that it is immutable, that it should be without any side effects, and that it should be transferable. It is therefore natural to declare explicitly these patterns as a simple way to do documentation.

您可以在项目中引入一组自定义注释，如下所示：

You could introduce a set of custom annotations like the following into a project:

• @ValueObject

• @ValueObject

• @Entity或@DomainEntity（为了防止所有技术框架中相似名称的注释出现任何歧义）

• @Entity or @DomainEntity (to prevent any ambiguity with the annotations of similar names from all the technical frameworks)

• @DomainService

• @DomainService

• @DomainEvent

• @DomainEvent

您可以使用属性显式声明后果。

And you can declare the consequences explicitly by using the properties.

每个类别的类都带有预定义的属性。例如，值对象应该具有值标识、不可变并且没有副作用。您可以通过使用注释上的注释轻松地在注释系统中明确这一点，如下所示：

Each category of class comes with predefined properties. For example, a value object should have identity by value, should be immutable, and should be side effect free. You can easily make this explicit in a system of annotations by using annotations on annotations, as shown here:

点击这里查看代码图片

Click here to view code image

1 @不可变
2 @SideEffectFree
3 @IdentityByValue
4 公共@interface ValueObject {
5 ...

1  @Immutable
2  @SideEffectFree
3  @IdentityByValue
4  public @interface ValueObject {
5  ...

当您将一个类标记为值对象时，您也可以使用元注释间接标记它。这是一种将属性分组到捆绑包中的便捷方法，只需一个等效声明即可声明所有属性。当然，bundle应该有明确的名称和含义；它不应该只是一堆随机的属性。

When you mark a class as being a value object, you indirectly mark it with the meta annotations as well. This is a convenient way to group properties that go together into bundles, to declare them all with only one equivalent declaration. Of course, a bundle should have a clear name and meaning; it should not be just a random bunch of properties together.

这种方法可以额外实施设计和架构。例如@DomainEntity，@DomainService、 和@DomainEvent暗示是域模型的一部分，并且可能对允许的依赖项进行相关限制，这些都可以通过静态分析来强制执行。

This approach enables additional enforcement of the design and architecture. For example @DomainEntity, @DomainService, and @DomainEvent imply being part of a domain model and perhaps related restrictions on the allowed dependencies, which can all be enforced with static analysis.

正如本章稍后所述，您可以在 Java 中的包上添加注释，以便一个位置的声明共同标记包的每个元素。您可以以“除非另有说明”的方式利用这一点。例如，您可以定义一个名为 的自定义注释@FunctionalFirst，该注释将放置在整个包上，这意味着默认情况@Immutable下@SideEffect-Free适用于每种类型，除非在特定类型上明确声明了其他内容。

As described later in this chapter, you can put annotations on packages in Java so that a declaration in one place collectively marks every element of the package. You can take advantage of this in an “unless specified otherwise” fashion. For example, you could define a custom annotation named @FunctionalFirst, meant to be put on whole packages, which would mean @Immutable and @SideEffect-Free by default for every type, unless something else were stated explicitly on a particular type.

还有许多其他感兴趣的模式和原型目录，可以有效地表达大量设计和建模知识。它们提供与开发人员工作、设计以及建模和解决基础设施问题相关的现成知识和词汇。但您可以更进一步，将标准类别扩展到更细粒度的类别。

There are many other catalogs of patterns and stereotypes of interest to express efficiently a lot of design and modeling knowledge. They provide ready-made knowledge and vocabulary related to your job as a developer, about design, and about modeling and solving infrastructure problems. But you can go further and extend the standard categories into finer-grained categories.

例如，可以细化值对象的种类。Martin Fowler 写了关于数量模式、空对象模式、特殊情况模式和范围模式的文章，这些都是值对象的特殊情况。另外，货币模式是数量模式的特例。您可以使用所有这些模式，并选择最具体的一种。例如，如果适用，您可以选择范围而不是值对象，因为众所周知，范围是值对象。如果这样做，您可以明确表示范围是值对象的特殊情况，并且在注释上带有注释：

For example, it is possible to refine the kind of value object. Martin Fowler wrote about the quantity pattern, the null object pattern, the special case pattern, and the range pattern, which are all specialized cases of value objects. In addition, the money pattern is a special case of the quantity pattern. You can use all these patterns, choosing the most specific one possible. For example, you could chose range over just value object if it applies, as it is common knowledge that a range is a value object. If you did this, you could make it explicit that a range is a special case of a value object with an annotation on the annotation:

点击这里查看代码图片

Click here to view code image

1 @ValueObject
2 公共@interface范围{
3 ...

1  @ValueObject
2  public @interface Range {
3  ...

您还可以创建自己的变体。在一个项目中，我有很多价值对象，但它们远不止这些。它们也是策略模式的实例，域模式相当于策略模式。更重要的是，在金融业务领域，我们通常将其称为标准市场惯例。所以我创建了自己的@Convention注释并明确表示它同时是一个值对象和一个策略：

You can also create your own variants. In one project, I had a lot of value objects, but they were more than that. They were also instances of the policy pattern, the domain pattern equivalent of the strategy pattern. More importantly, in the business domain of finance, we would usually call them standard market conventions. So I created my own @Convention annotation and made it clear that it was at the same time a value object and a policy:

点击这里查看代码图片

Click here to view code image

1 @ValueObject
2 @政策
3 公共@interface约定{
4 ...

1  @ValueObject
2  @Policy
3  public @interface Convention {
4  ...

使用有意义的注释包名称

Using Meaningful Annotation Package Names

创建自定义注释时，必须选择其包名称。您可以选择具有特定含义的包名称。我喜欢在包名称中编码一个想法的参考位置。例如，当注释取自一本书时，我可能会使用书名或书名或作者的缩写，例如 com.acme.annotation.gof 代表四人帮的书，com.acme.annotation.gof 代表四人帮的书。acme.annotation.poeaa 用于《企业应用程序架构模式》一书，com.acme.annotation.ddd 用于《领域驱动设计》一书。对于没有一本金书的标准知识，我可能会根据字段命名包（例如，com.acme.annotation.algebra）。

When you create a custom annotation, you have to choose its package name. You can choose for a package name to have a particular meaning. I like to encode a reference place for an idea in the package name. When the annotation is drawn from a book, for example, I might use the book name or an abbreviation of the book name or authors, such as com.acme.annotation.gof for a book by the Gang of Four, com. acme.annotation.poeaa for the book Patterns of Enterprise Application Architecture, and com.acme.annotation.ddd for the book Domain-Driven Design. For standard knowledge with no one golden book, I might name the package after the field (for example, com.acme.annotation.algebra).

劫持标准注释

Hijacking Standard Annotations

Java 世界中的许多框架都使用注释作为配置形式。例如，JPA（Java Persistence API）和 Spring Framework 提供了 XML 和注释之间臭名昭著的选择。尽管我提倡将注释用于文档目的，但我并不热衷于使用注释来替代编写代码。我更喜欢一些 .Net 项目（例如 Fluent NHibernate）中使用纯代码定义对象到关系映射的方法。

Many frameworks in the Java world use annotations as a form of configuration. For example, JPA (Java Persistence API) and Spring Framework offer the infamous choice between XML and annotations. Even though I advocate using annotations for documentation purposes, I am not a big fan of using annotations as an alternative to writing code. I prefer the approach found in some .Net projects, such as Fluent NHibernate, of using plain code to define the object-to-relational mappings.

然而，此时在 Java 中，您仍然必须使用注释，除非您更喜欢 XML（我不喜欢）。当您使用注释来驱动框架的行为时，注释实际上是代码，并且由于它们中的大多数与持久性或 Web 服务等基础设施问题相关，因此它们通常有一个恼人的习惯，即用非域噪声污染域类。

However, in Java at this time, you still have to use annotations, unless you prefer XML (which I do not). When you use annotations to drive the behavior of frameworks, the annotations are code indeed, and since most of them relate to infrastructure concerns such as persistence or web service, they often have the annoying habit of polluting domain classes with non-domain noise.

除了我的小抱怨之外，您可能想知道这些标准注释是否有任何文档价值。因为它们至少是代码，所以注释记录了它们正在做什么——就像设计良好的代码一样。他们讲述什么。

Aside from my little rant, you probably wonder whether these standard annotations have any documentation value. Because they are code, at a minimum, the annotations document what they are doing—just like well-designed code. They tell the what.

让我们考虑一些特定文档兴趣的示例：

Let’s consider a few examples of particular documentation interest:

• 刻板化注释（Spring）：这组注释包括@Service、@Repository和@Controller。它们用于构造类，您可以声明它们以注册到依赖项注入机制中。事实上，它们给注释起@Component了更有意义的别名，这是一种很好的方式来劫持这些嘈杂的注释，以获得对人类更有意义的东西，而不仅仅是对 Spring 更有意义。

• Stereotyping annotations (Spring): This set of annotations includes @Service, @Repository, and @Controller. They are used to stereotype classes, and you can declare them for registration into the dependency injection mechanism. In fact, they alias the @Component annotation with more meaning, which is a nice way to hijack these noisy annotations for something more meaningful for humans rather than just for Spring.

• 创建自定义构造型 (Spring)：此方法还支持您自己的自定义注释，前提是您使用@Component元注释对它们进行注释。

• Creating custom stereotypes (Spring): This approach also supports your own custom annotations, provided that you annotate them with the @Component meta annotation.

• @Transactional(Spring)：注释@Transactional用于声明事务边界和规则，通常在服务上。如果您有六边形架构，那么事务服务应该是位于域模型之上的自己的薄层中的应用程序服务。因此，您可以确定这个 Spring 注释本身也具有@Application-ServiceDDD 意义。因为大多数 Spring 注释也是元注释，所以您实际上可以定义自己的@ApplicationService注释并将其标记为，@Transactional以便以 Spring 也可以识别并发挥其魔力的方式表达您的意图。

• @Transactional (Spring): The @Transactional annotation is used to declare transactional boundaries and rules, typically on a service. If you have a hexagonal architecture, the transactional services should be your application services in their own thin layer on top of the domain model. You could thus decide that this Spring annotation in itself also means @Application-Service in the DDD sense. Because most Spring annotations are also meta annotations, you could actually define your own @ApplicationService annotation and mark it as @Transactional in order to express your intent in a way that Spring can recognize for doing its magic, too.

• @Inheritance(JPA)：注释@Inheritance及其朋友可用于直接记录有关如何在类层次结构和相应的数据库模式之间进行映射的设计决策。这与 Martin Fowler 的《企业应用程序架构模式》一书中的相应模式直接相关。例如，@Inheritance(strategy=JOINED)对应于单表继承模式²（但不幸的是，使用了另一个名称）。

  2. Martin Fowler，“单表继承”，ThoughtWorks，http: //martinfowler.com/eaaCatalog/singleTableInheritance.html

• @Inheritance (JPA): The @Inheritance annotation and its friends can be used to directly document design decisions on how to do the mapping between a class hierarchy and a corresponding database schema. This directly relates to the corresponding patterns from Martin Fowler’s book Patterns of Enterprise Application Architecture. For example, @Inheritance(strategy=JOINED) corresponds to the single-table inheritance pattern² (but, unfortunately, under another name).

  2.Martin Fowler, “Single Table Inheritance,” ThoughtWorks, http://martinfowler.com/eaaCatalog/singleTableInheritance.html

• RESTful Web 服务（JAX-RS 注释）：这组注释具有明确的声明性：@Path标识 URI 路径、@GET声明GET请求方法并将@Produces媒体类型定义为参数。生成的代码在很大程度上是自我记录的。此外，Swagger 等工具可以利用这些注释来生成 API 的实时文档。

• RESTful web service (JAX-RS annotations): This set of annotations is clearly declarative: @Path identifies the URI path, @GET declares the GET request method, and @Produces defines the media type as a parameter. The resulting code is self-documented to a large extent. Furthermore, tools like Swagger can exploit these annotations to generate living documentation of the API.

可以依赖标准注释来获取其特定的文档价值，但这几乎总是限于技术问题，其中注释就像特定的声明性代码一样，它告诉了“内容”，但不告诉“为什么”。正如前面提到的，有时可以扩展标准机制来传达额外的含义，同时仍然可以与您所依赖的框架很好地配合。

It is possible to rely on the standard annotations for their particular documentation value, but this is almost always limited to technical concerns, where the annotation is just like particularly declarative code in that it tells the what but not the why. As mentioned earlier, it is sometimes possible to extend the standard mechanism to convey additional meaning while still playing nicely with the frameworks you depend on.

标准注解：@Aspect 和面向方面的编程

Standard Annotation: @Aspect and Aspect-Oriented Programming

Spring Pet Clinic 通过展示如何设置一个简单的方面来监视每个存储库的调用计数和调用调用时间，从而演示了面向方面的编程 (AOP) 。³

The Spring Pet Clinic demonstrates aspect-oriented programming (AOP) by showing how to set up a simple aspect that monitors call count and call invocation time for every repository.³

3. https://github.com/spring-petclinic/spring-framework-petclinic/blob/master/src/main/java/org/springframework/samples/petclinic/util/CallMonitoringAspect.java

3.https://github.com/spring-petclinic/spring-framework-petclinic/blob/master/src/main/java/org/springframework/samples/petclinic/util/CallMonitoringAspect.java

这里有趣的是，“监视每个存储库”的需求在切面声明中按字面意思描述，如以下使用@AspectSpring AOP 注释的摘录所示。

It is interesting here that the requirement “to monitor every repository” is described literally in the aspect declaration, as shown in the following excerpt annotated with the @Aspect annotation from Spring AOP.

点击这里查看代码图片

Click here to view code image

1 @方面
2 公共类CallMonitoringAspect {
3 ...
4 @Around("在(@org.springframework.stereotype.Repository *)")
5    公共对象调用（ProceedingJoinPoint joinPoint）抛出
可投掷{
6 ...
7}
8 ...
9 }

1  @Aspect
2  public class CallMonitoringAspect {
3    ...
4    @Around("within(@org.springframework.stereotype.Repository *)")
5    public Object invoke(ProceedingJoinPoint joinPoint) throws
Throwable{
6      ...
7    }
8  ...
9  }

这种表达能力是可能的，因为代码已经通过有意义的@Repository构造型得到了增强。这完美地说明了如何通过明确的设计决策来增强代码，从而能够以我们人类的思维方式与工具对话。

This expressiveness is possible because the code has been augmented with the meaningful @Repository stereotype. This illustrates perfectly how augmenting the code with explicit design decisions makes it possible to talk to tools the way we humans think.

默认注释或除非必要

Annotation by Default or Unless Necessary

在设计自定义注释来表达属性时，您可以选择在满足或不满足属性时为情况创建注释：

When designing custom annotations to express properties, you have a choice of creating an annotation for the case when the property is met or when it’s not met:

• @Immutable或者@Mutable

• @Immutable or @Mutable

• @NonNull或者@Nullable

• @NonNull or @Nullable

• @SideEffectFree或者@SideEffect

• @SideEffectFree or @SideEffect

您可以创建两者并让个人决定选择哪一个，但这可能会造成不一致，在这种情况下注释根本没有任何意义。

You may create both and let individuals decide which one to choose, but that might create inconsistencies, in which case the annotation means nothing at all.

您可以决定要推广的替代方案，以便在许多地方添加注释成为营销活动；例如，使用@NonNull“Everywhere”将鼓励将所有内容设为非空。没有注释则表明可为空。

You may decide on an alternative that you want to promote so that having the annotation in many places becomes a marketing campaign; for example, using @NonNull everywhere will encourage making everything non-null. No annotation then suggests nullability.

另一方面，您可能会认为注释是噪音，并认为注释越少越好。在这种情况下，默认且首选的选择应该是无注释，并且您将仅使用注释来声明与默认值的偏差。如果团队偏好默认情况下每个类都是不可变的，那么您将注释可变类，因为您希望同事注意到：“哦，这个类非常出色@Mutable！”

On the other hand, you might consider that annotations are noise and think that the fewer annotations the better. In this case, the default and preferred choice should be no annotation, and you would use an annotation only to declare a deviation from the default. If the team preference is to have every class immutable by default, you would annotate mutable classes because you want your colleagues to notice: “Oh, this class is exceptionally @Mutable!”

处理多种模块

Dealing with Many Kinds of Modules

包是 Java 和其他语言中最明显的模块。但包 xyz 实际上定义了多个模块：其直接成员的模块 ( x.y.z.*) 以及还包括其子包中包含的每个工件的模块 ( x.y.z.**)。类似地，类也代表其成员字段、方法和嵌套类的“模块”，例如x.y.z.A#和x.y.z.$。

Packages are the most obvious modules in Java and in other languages. But a package x.y.z actually defines more than one module: the module of its direct members (x.y.z.*) and the module that also include every artifact included in its subpackages (x.y.z.**). Similarly, a class also represents a “module” for its member fields, methods, and nested classes—for example, x.y.z.A# and x.y.z.$.

像 Eclipse 这样的 IDE 中的“工作集”还定义了另一个逻辑分组，类似于模块，作为类和其他资源的简单集合。Ant 等工具还使用文件列表和正则表达式定义文件集，例如{x.y.z.A, x.y.z.B, x.y.*.A}. 与模块一样，工作集和文件集通常被命名以方便参考。

The “working sets” in an IDE like Eclipse also define another logical grouping, similar to modules, as simple collections of classes and other resources. Tools like Ant also define filesets using lists of files and regular expressions—for example, {x.y.z.A, x.y.z.B, x.y.*.A}. Like modules, working sets and filesets are usually named for easy reference.

源文件夹（例如，src/main/java 或 src/test/java）显然定义了粗粒度的元素分组。Maven 模块以子项目的规模定义更大的模块。面向方面编程的切入点还定义了跨各种“真实”模块的逻辑分组元素。

Source folders (for example, src/main/java or src/test/java) obviously define coarse-grained groupings of elements. Maven modules define bigger modules, at the scale of subprojects. Pointcuts of aspect-oriented programming also defines logical groupings elements across various “real” modules.

继承和实现也隐式定义模块，例如“类的每个子类或接口的实现”为x.y.z.A+，如果它包含每个嵌套成员的每个成员，则它是x.y.z.A++。

Inheritance and implementation implicitly define modules, too, such as “every subclass of a class or implementation of an interface” as x.y.z.A+, and if it includes every member of every nested member, it is x.y.z.A++.

构造型隐式定义了其出现的集合。例如，值对象模式隐式定义了作为值对象的每个类的逻辑集。

A stereotype implicitly defines the set of its occurrences. For example, the value object pattern implicitly defines the logical set of every class that is a value object.

模型-视图-控制器 (MVC) 和知识级别等协作模式还意味着逻辑分组，例如 MVC 的模型部分或知识级别模式的每个级别（知识级别或操作级别）。

Collaboration patterns such as Model–View–Controller (MVC) and knowledge level also imply logical groupings such as the model part of MVC or each level of the knowledge level pattern (knowledge level or operational level).

设计模式还根据模式中所扮演的角色来定义逻辑分组（例如，“抽象工厂模式中的每个抽象角色”都是@AbstractFactory.Abstract.*）。

Design patterns also define logical groupings by the role played within the pattern (for example, “Every abstract role in the Abstract Factory pattern” would be @AbstractFactory.Abstract.*).

层、域、有界上下文和聚合根等概念隐含了许多其他模块或准模块。

There are many other modules or quasi-modules implied by concepts like layers, domains, bounded contexts, and aggregate roots.

大型模块的问题在于它们包含大量项目，这通常需要进行积极的过滤，甚至可能需要进行排名以仅考虑更多元素中的N个最重要的元素。

The problem with large modules is that they contain huge numbers of items, which often necessitates aggressive filtering and may even require ranking to consider only the N most important elements out of many more.

实践中的模块范围增强

Module-Wide Augmentation In Practice

所有用附加知识来增强代码的技术都适用于模块范围的知识：注释、命名约定、sidecar 文件、元数据数据库和 DSL。

All the techniques to augment code with additional knowledge apply for module-wide knowledge: annotations, naming conventions, sidecar files, metadata database, and DSL.

将文档添加到 Java 包的常见方法是使用名为 package-info.java 的特殊类作为 Javadoc 和有关包的任何注释的位置。请注意，这个具有神奇名称的特殊伪类实际上是 sidecar 文件的示例。

A common way to add documentation to a Java package is to use a special class named package-info.java as a location for the Javadoc and any annotation about the package. Note that this special pseudo-class with a magic name is actually an example of a sidecar file.

C# 模块通常包含项目，其中可以有程序集信息描述：

C# modules often contain projects, which can have assembly information descriptions:

1 AssemblyInfoDescription("包注释")

1  AssemblyInfoDescription("package comment")

在大多数编程语言中，包或命名空间命名约定也可用于声明设计决策。例如，something.domain可用于将包或命名空间标记为域模型。

In most programming languages, package or namespace naming conventions can also be used to declare design decisions. For example, something.domain can be used to mark a package or namespace as a domain model.

基本原理是什么？

What’s in a Rationale?

任何决定都是在一定背景下发生的，并且是经过深思熟虑的问题答案之一。因此，基本原理不仅是所选决策背后的原因，而且还包括以下所有内容：

Any decision happens in a context and is one of the considered answers to a problem. Therefore, a rationale is not only the reason behind a chosen decision, it is also all of the following:

• 当时的背景：背景包括主要的利害关系和关注点，例如当前负载（“只有 1000 个最终用户每周使用该应用程序一次”）或当前优先级（“优先级是尽快探索市场与产品的契合度”）尽可能”）或假设（“预计不会改变”）或人员考虑（“开发团队不想学习 JavaScript”）。

• The context at the time: The context includes the main stakes and concerns, for example the current load (“Only 1000 end users using the application once a week”) or the current priority (“Priority is exploring the market-product fit as quickly as possible”) or an assumption (“This is not expected to change”) or a people consideration (“The development teams don’t want to learn JavaScript”).

• 选择背后的问题或要求：问题的示例包括“页面必须在 800 毫秒内加载才能不丢失访问者”和“停用 VB6 模块”。

• The problem or requirement behind the choice: Examples of problems are “The page must load in less than 800ms to not lose visitors” and “Decommission the VB6 module.”

• 决定本身而不是所选择的解决方案，并附有一个或多个主要原因：决定和原因的示例是“通用语言仅用英语单词表达，因为它更简单并且每个当前利益相关者更喜欢这种方式”和“这个外观通过漂亮的 API 公开遗留系统，因为没有充分的理由重写遗留系统，但我们仍然希望像全新的一样方便地使用它。”

• The decision itself instead of the chosen solution, with the main reason or reasons: Examples of decisions and reasons are “The ubiquitous language is expressed with English words only, as it’s simpler and every current stakeholder prefers it that way” and “This facade exposes the legacy system through a pretty API because there is no good reason to rewrite the legacy but we still want to consume it with the same convenience as if it were brand new.”

• 认真考虑的主要替代方案，也许是为什么没有选择它们，或者如果情况不同，为什么会选择它们：替代方案的示例是“如果需求更加标准，购买现成的解决方案将是更好的选择” ”、“图形结构会更强大，但更难与用户的 Excel 电子表格映射”，以及“如果我们没有对当前的 Oracle 数据库进行所有这些投资，NoSQL 数据存储将是更好的选择。”

• The main alternatives that were considered seriously and perhaps why they were not selected or why they would be selected if the context were different: Examples of alternative are “Buying an off-the-shelves solution would be a better choice if the needs were more standard,” “A graph structure would be more powerful but is harder to map with the Excel spreadsheets of the users,” and “A NoSQL datastore would be a better choice if we didn’t have all this investment with our current Oracle database.”

正如@CarloPescio 在关于自记录代码的对话中所建议的那样，一般来说，设计原理很大程度上与丢弃的选项有关，因此通常不在代码中。

As @CarloPescio suggested in a conversation on self-documenting code, generally speaking, design rationale is very much about discarded options and so is not typically in the code.

明确理由

Making the Rationale Explicit

您可以通过多种方式记录重要决策背后的理由：

You can record the rationale behind important decisions in a number of ways:

• 特别文档：您需要一份关于需求的明确文档，包括所有质量属性。它需要缓慢地发展，但至少每年一次；仅对于跨越系统大范围的主要属性才需要这样的文档，而不是对于更多的本地决策。第 12 章“实时架构文档”描述了决策日志作为架构问题方法的示例。

• Ad hoc document: You need an explicit document about the requirements, including all quality attributes. It needs to evolve slowly but still at least once a year; such a document is needed only for the main attributes that span large areas of the system, not for more local decisions. Chapter 12, “Living Architecture Documentation,” describes a decision log as an example of that approach for architectural matters.

• 注释：记录决策的注释可以包含记录基本原理的字段：@MyAnnotation(rationale ="We only know how to do that way")。

• Annotations: Annotations that document a decision could have fields to record the rationale: @MyAnnotation(rationale ="We only know how to do that way").

• 博客文章：博客文章比注释甚至临时文档需要更多的时间来编写，良好的写作风格确实很有帮助。然而，你提供了对决策背后的推理和人文背景的人性化描述，即使字里行间提到了政治和个人议程，这使得它很有价值。当对过去的决定产生疑问时，也可以搜索和扫描博客文章。

• Blog post: A blog post takes more time to write than annotations or even an ad hoc document, and a good writing style is really helpful. However, you provides a human account of the reasoning and the human context behind a decision, even with the politics and personal agenda mentioned between the lines, and this makes it valuable. A blog post may also be searched and scanned when a question arises on a past decision.

超越文档：动机设计

Beyond Documentation: Motivated Design

记录下这个道理，不仅是为了子孙后代或者未来的自己，也是为了以后的自己。当你这样做的时候，它现在也很有用。你需要听什么是困难的信号有些东西可以改进。如果很难找出理由或背景，则可能没有足够认真地考虑该决定，这应该引起警惕。

Recording the rationale is not just for future generations or your future self; it is also useful right now, at the time you do it. You need to listen to what’s difficult as a signal that something could be improved. If it is hard to come up with a rationale, or a context, perhaps the decision was not thought about seriously enough, and this should be an alert.

如果很难为某个决策提出两到三个可靠的替代方案，那么也许会选择第一个合适的解决方案，而无需做任何工作来探索更简单或更好的解决方案。您当前的决定可能不是最佳的，并且可能会造成未来失去机会的后果。当然，一个理由可能是“选择第一个合适的解决方案以尽快进入市场”，但至少这个决定是经过深思熟虑的，相关人员了解后果，并准备好下次重新考虑。

If it is hard to come up with two or three credible alternatives to a decision, then perhaps the first solution that fit was chosen, without any work being done to explore simpler or better solutions. Your current decision might not be optimal, and it can have consequences as lost opportunities in the future. Of course, one rationale may be “First solution that fit was chosen to go to market as quickly as possible,” but at least this decision is deliberate, and those involved understand the consequence and can be ready to reconsider it next time.

如果没有经过深思熟虑的设计决策，并且完全缺乏技能，您将只能拥有一个随机的软件结构。你最终只会得到一堆细节，而处理它的唯一方法就是猜测所涉及的意图。这通常是您在遗留代码中必须处理的问题，我们将在第 14 章“记录遗留应用程序”中详细讨论。我的观点是，专注于明确理由有助于做出更好的决策和更好的软件。

In the absence of deliberate design decisions, and with a complete lack of skills, you will just have a random software structure. You just end up with a pile of details, and the only way to deal with it is to guess the intentions involved. This is typically the issues you have to deal with in legacy code, which we discuss in detail in Chapter 14, “Documenting Legacy Applications.” My point is that the focus on making a rationale explicit helps make better decisions and better software.

避免记录猜测

Avoid Documenting Speculation

在《构建微服务》一书中，Sam Newman 建议不要记录推测性需求的解决方案。他描绘了一幅传统架构文档的批判图景，用很多页和很多图表解释了完美的系统将是什么样子，但完全忽略了在实际构建它并使其工作时出现的任何意外的未来障碍。

In the book Building Microservices, Sam Newman advises against documenting solutions to speculative needs. He paints a critical picture of traditional architecture documentation that explains with many pages and many diagrams how the perfect system will be but ignoring completely any unexpected future impediment when it comes to actually build it and make it work.

相反，理由是根据实际需要做出的已被证明是必要的决定。在增量方法中，例如新兴设计，我们逐片扩展解决方案，每个片都由每个时刻最重要的需求驱动。我们经常以准时制的方式工作，正是因为它是投机的解毒剂：我们只在有必要建造它时才建造它。

In contrast, rationales are decisions taken on actual needs that have been proven to be necessary. In incremental approaches, such as emerging design, we grow the solution slice by slice, and each slice is driven by the most important need at each instant. We often work in a just-in-time fashion, precisely because it is an antidote to speculation: We build it just when it becomes necessary to be built.

总的来说，您应该只记录已经构建的内容，以响应实际需求。

Overall, you should document only what has been built, in response to actual needs.

技能作为预先记录的理由

Skills as Pre-Documented Rationales

许多小决策的思考过程已经被解决并记录在文献中。例如，单一职责原则要求将一个做两件事的类分成两个各做一件事的类。没有必要记录每次发生的特定事件，但您可以在一个地方记录一次您一贯遵循的每项原则；我将其称为“承认你的影响”模式，并将在本章稍后进行描述。

The thinking process for many small decisions has already been solved and documented in the literature. For example, the single responsibility principle says to split a class that does two things into two classes that do one thing each. There is no need to document each occurrence of a particular happening, but you may document once, in a single place, each of the principles you consistently follow; I call this the acknowledge your influences pattern and describe it a little later in this chapter.

记录作为变革推动者的基本原理

Recording the Rationale as an Enabler for Change

了解过去决策背后的所有原因可以使您更成功地做出改变，因为您可以故意尊重或拒绝每个决策。可靠地了解这些决定的最佳方法是将它们记录下来；否则推理就会忘记（见图4.4））。如果没有过去每个决定背后的明确理由，您可能想知道更改是否会对您没有想到的问题产生意想不到的影响。如果不了解过去的决定，您可能永远没有足够的把握决定改变，并且现状将占主导地位，即使改进的机会就在您眼前。或者，如果您所做的更改引发了您因未记录而无法看到的被遗忘的问题，那么您实际上可能会无意中造成伤害。

Knowing all the reasons behind past decisions can enable you to more successfully make changes because you can either respect or reject each of those decisions deliberately. The best way to know about those decisions in a reliable way is to have them recorded; otherwise, the reasoning will be forgotten (see Figure 4.4). Without the explicit rationale behind each past decision, you might wonder if a change has unexpected impacts with respect to a concern you don’t have in mind. Without knowing about past decisions, you may never be sure enough to decide to change, and the status quo will dominate, even though the opportunity to improve is there in front of your eyes. Alternatively, you may actually cause harm inadvertently if you make a change that triggers a forgotten concern that you cannot see because it was not recorded.

宣告你的风格

Declaring Your Style

由于画家往往属于特定的绘画流派（例如超现实主义、立体主义），因此软件开发人员会与不同的思想流派保持一致。有些画家可以在一幅作品的风格之间切换到另一幅作品；同样，开发人员也许能够以非常函数式编程风格创建一个模块，其中所有内容都是纯粹且不可变的，然后使用语义技术和面向图形的存储创建另一个模块。

As painters tend to belong to specific painting schools (for example, Surrealism, Cubism), software developers align themselves with various schools of thoughts. Some painters can switch between styles from one work to another; similarly, a developer might be able to create a module in a very functional programming style, with everything pure and immutable, and then create another module using semantic technologies and graph-oriented stores.

为了向文档读者提供上下文，声明您为某些代码区域（通常是模块或项目）选择的样式和主要范例（如果有）非常有用。这个总体陈述可能看起来类似于一个或多个团队的简历：

To provide context for documentation readers, it is useful to declare the style and the main paradigm, if any, that you have chosen for some area of code—typically for a module or for a project. This overall statement might look similar to a resume for the team or teams:

• 建模范例（例如 DDD）

• Modeling paradigms (for example, DDD)

• 团队成员关注的作者

• Authors the team members follow

• 团队成员读过的书和经常读的博客

• Books the team members have read and blogs they often go read

• 团队成员熟悉的语言和框架

• Languages and frameworks the team members are familiar with

• 任何重要的灵感，例如“Stripe 作为开发人员友好性的灵感”

• Any kind of inspiration that matters, such as “Stripe as an inspiration for developer-friendliness”

• 团队成员迄今为止完成的典型项目类型（例如，Web、服务器、嵌入式）

• Typical kinds of projects the team members have mostly done so far (for example, web, server, embedded)

为了作为重构证据，此信息应驻留在模块或项目本身中。它可以通过包 (Java) 上的 (Styles.FP)、AssemblyInfo (.Net) 上的属性等注释来完成@Style，或者通过在模块或项目根部使用具有键/值语法的 style.txt 文件来完成。

To be refactoring proof, this information should reside within the module or project itself. It can be done with annotations such as @Style (Styles.FP) on packages (Java), attributes on the AssemblyInfo (.Net), or by using a style.txt file with a key/value syntax at the root of the module or project.

声明您的风格有助于强制代码库内的一致性。

Declaring your style helps enforce consistency within the code base.

提交指南

Commit Guidelines

提交指南的一个很好的例子是 Angular 提交指南¹⁰ ，它指定了提交消息必须如何格式化的严格规则。Angular 网站称，这些规则“会带来更易读的消息，在查看项目历史记录时很容易遵循。而且，我们还使用 git 提交消息来生成 AngularJS 更改日志。” 根据这套特定的指导方针，提交消息的结构必须为标头部分、可选的正文部分和可选的页脚部分，每个部分均由空行分隔，如下所示：

A good example of commit guidelines is the Angular commit guidelines,¹⁰ which specify strict rules for how the commit messages must be formatted. These rules, says the Angular website, lead “to more readable messages that are easy to follow when looking through the project history. But also, we use the git commit messages to generate the AngularJS change log.” According to this particular set of guidelines, the commit message must be structured as a header section, an optional body section, and an optional footer section, each separated by a blank line, as shown here:

10.AngularJS， https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit

10.AngularJS, https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit

点击这里查看代码图片

Click here to view code image

1   <类型> ( <范围> ): <主题>
2
3   <正文>
4
5   <页脚>

1  <type>(<scope>): <subject>
2
3  <body>
4
5  <footer>

1 feat(tradeFeeding)：支持负优惠券的交易供给
2 债券
3
4 有些债券的票面利率为负，例如-0.21%。
5 更改验证以不拒绝债券交易
6 负优惠券。
7
8 关闭#8125

1 feat(tradeFeeding): Support trade feeding for negative-coupon
2 bonds
3
4 Some bonds have negative coupon rates, e.g. -0.21 percent.
5 Change the validation to not reject trades on bonds
6 with negative coupons.
7
8 Closes #8125